341 lines
11 KiB
YAML
341 lines
11 KiB
YAML
title: Carts
|
|
domain: store
|
|
routes:
|
|
- method: POST
|
|
path: /carts
|
|
- method: GET
|
|
path: /carts/:id
|
|
- method: POST
|
|
path: /carts/:id
|
|
- method: POST
|
|
path: /carts/:id/line-items
|
|
- method: POST
|
|
path: /carts/:id/line-items/:line_id
|
|
- method: DELETE
|
|
path: /carts/:id/line-items/:line_id
|
|
- method: POST
|
|
path: /carts/:id/payment-sessions
|
|
- method: DELETE
|
|
path: /carts/:id/payment-sessions/:provider_id
|
|
- method: POST
|
|
path: /carts/:id/payment-method
|
|
- method: POST
|
|
path: /carts/:id/shipping-methods
|
|
- method: DELETE
|
|
path: /carts/:id/discounts/:code
|
|
route: /carts
|
|
description: >
|
|
A Cart is the preliminary step to an Order. The Cart holds a collection of
|
|
items that the customer wishes to purchase, along with the customer's
|
|
preferred payment and shipping method.
|
|
endpoints:
|
|
- path: /
|
|
method: POST
|
|
title: Create a Cart
|
|
body:
|
|
- name: region_id
|
|
type: String
|
|
required: false
|
|
description: Id of the region to associate the cart with.
|
|
- name: items
|
|
type: List
|
|
required: false
|
|
description: List of objects with `variantId` and `quantity`.
|
|
description: >
|
|
Creates a Cart within the given region and with the initial items. If no
|
|
`region_id` is provided the cart will be associated with the first Region
|
|
available. If no items are provided the cart will be empty after creation.
|
|
If a user is logged in the cart's customer id and email will be set.
|
|
- path: /:id
|
|
method: GET
|
|
title: Retrieve a Cart
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
description: >
|
|
Retrieves an existing cart.
|
|
- path: /:id
|
|
method: POST
|
|
title: Update a Cart
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
body:
|
|
- name: region_id
|
|
type: String
|
|
description: Id of a region.
|
|
- name: email
|
|
type: String
|
|
description: >
|
|
Customer's email where they will receive transactional emails etc.
|
|
- name: billing_address
|
|
type: Address
|
|
description: >
|
|
The billing address for the order.
|
|
- name: shipping_address
|
|
type: Address
|
|
description: >
|
|
The shipping address for the order. Will be sent to the fulfillment
|
|
provider when the items are ready to be shipped.
|
|
- name: discounts
|
|
type: List
|
|
description: >
|
|
A list of objects with `code` that represents a discount code to be
|
|
applied to the cart.
|
|
description: >
|
|
Updates an existing cart with the provided data. Updating the `region_id`
|
|
will change the prices of the items in the cart to match the prices
|
|
defined for the region. You can apply multiple discounts at once by
|
|
calling the endpoint with an array of discounts.
|
|
- path: /:id/line-items
|
|
method: POST
|
|
title: Add line item
|
|
params:
|
|
- name: id
|
|
type: String
|
|
body:
|
|
- name: variant_id
|
|
type: String
|
|
required: true
|
|
description: The id of the variant that should be added to the cart.
|
|
- name: quantity
|
|
type: Integer
|
|
required: true
|
|
description: >
|
|
The quantity of the variant to add to the cart. Must be
|
|
greater than 0.
|
|
- name: metadata
|
|
type: Object
|
|
description: >
|
|
Optional metadata that may be needed for display purposes or other
|
|
functionality.
|
|
- path: /:id/line-items/:line_id
|
|
method: POST
|
|
title: Update line item
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart to update.
|
|
- name: line_id
|
|
type: String
|
|
description: Id of the line to update.
|
|
body:
|
|
- name: quantity
|
|
type: Integer
|
|
description: The desired quantity of the line item.
|
|
description: >
|
|
Updates the quantity of a line item. If the variant associated with the
|
|
line item is stock managed, the endpoint will respond with an error when
|
|
the inventory level cannot fulfill the desired quantity.
|
|
- path: /:id/line-items/:line_id
|
|
method: DELETE
|
|
title: Remove line item
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
- name: line_id
|
|
type: String
|
|
description: Id of the line item to remove.
|
|
description: >
|
|
Removes a the given line item from the cart.
|
|
- path: /:id/discounts/:code
|
|
method: DELETE
|
|
title: Remove discount code
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
- name: code
|
|
type: String
|
|
description: The discount code to remove
|
|
description: Removes a discount code from the cart.
|
|
- path: /:id/payment-sessions
|
|
method: POST
|
|
title: Create payment sessions
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
description: >
|
|
Initializes the payment sessions that can be used to pay for the items of
|
|
the cart. This is usually called when a customer proceeds to checkout.
|
|
- path: /:id/payment-sessions/:provider_id
|
|
method: DELETE
|
|
title: Delete payment session
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
- name: provider_id
|
|
type: String
|
|
description: >
|
|
Id of the provider that created the payment session to remove.
|
|
description: >
|
|
Deletes a payment session. Note that this will initialize a new payment
|
|
session with the provider. This is usually used if the payment session
|
|
reaches a state that cannot be recovered from.
|
|
- path: /:id/payment-method
|
|
method: POST
|
|
title: Add payment method
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
body:
|
|
- name: provider_id
|
|
type: String
|
|
required: true
|
|
description: >
|
|
Id of the provider that offers the payment method.
|
|
- name: data
|
|
type: Dictionary
|
|
description: >
|
|
Used to hold any data that the payment method may need to process the
|
|
payment. The requirements of `data` will be different across payment
|
|
methods, and you should look at your installed payment providers to
|
|
find out what to send.
|
|
description: >
|
|
Adds or updates the payment method that will be used to pay for the items
|
|
in the cart. The payment is not processed until the payment provider's
|
|
authorization functionality is called. You should consult with your
|
|
installed payment plugins to find information about how to authorize a
|
|
payment.
|
|
- path: /:id/shipping-methods
|
|
method: POST
|
|
title: Add shipping method
|
|
params:
|
|
- name: id
|
|
type: String
|
|
description: Id of the cart.
|
|
body:
|
|
- name: option_id
|
|
type: String
|
|
required: true
|
|
description: The id of the shipping option to use.
|
|
- name: data
|
|
type: Dictionary
|
|
description: >
|
|
Used to hold any data that the shipping method may need to process the
|
|
fulfillment of the order. Look at the documentation for your installed
|
|
fulfillment providers to find out what to send.
|
|
description: >
|
|
Adds a shipping method to the cart.
|
|
response: |
|
|
{
|
|
"cart": {
|
|
"_id": "5f68a234d694d000217a4d64",
|
|
"customer_id": "",
|
|
"region_id": "5f4cd57a5d1e3200214c0e4e",
|
|
"email": "",
|
|
"shipping_address": {
|
|
"_id": "5f68a234d694d000217a4d65",
|
|
"country_code": "US"
|
|
},
|
|
"items": [
|
|
{
|
|
"is_giftcard": false,
|
|
"has_shipping": false,
|
|
"returned": false,
|
|
"fulfilled": false,
|
|
"fulfilled_quantity": 0,
|
|
"returned_quantity": 0,
|
|
"_id": "5f72f79c2834b400216b1a54",
|
|
"title": "Line Item",
|
|
"description": "240x260",
|
|
"quantity": 1,
|
|
"thumbnail": "https://example-thumbnail.com",
|
|
"content": {
|
|
"unit_price": 303.2,
|
|
"variant": {
|
|
"_id": "5f4cf81a2ac41700211f6e63",
|
|
"barcode": "",
|
|
"image": "",
|
|
"published": true,
|
|
"inventory_quantity": 11,
|
|
"allow_backorder": false,
|
|
"manage_inventory": true,
|
|
"title": "1234",
|
|
"sku": "SKU1234",
|
|
"ean": "1111111111111",
|
|
"options": [
|
|
{
|
|
"_id": "5f4cf81a2ac41700211f6e64",
|
|
"value": "1234",
|
|
"option_id": "5f4cf81a2ac41700211f6e62"
|
|
}
|
|
],
|
|
"prices": [
|
|
{
|
|
"_id": "5f4cf81a2ac41700211f6e65",
|
|
"currency_code": "SEK",
|
|
"amount": 3180
|
|
},
|
|
{
|
|
"_id": "5f4cf81a2ac41700211f6e66",
|
|
"currency_code": "EUR",
|
|
"amount": 303.2
|
|
},
|
|
{
|
|
"_id": "5f4cf81a2ac41700211f6e67",
|
|
"currency_code": "DKK",
|
|
"amount": 2260
|
|
}
|
|
],
|
|
"metadata": {
|
|
"origin_country": "Portugal"
|
|
}
|
|
},
|
|
"product": {
|
|
"_id": "5f4cf81a2ac41700211f6e61",
|
|
"description": "100% Organic",
|
|
"tags": "",
|
|
"is_giftcard": false,
|
|
"images": [],
|
|
"thumbnail": "https://example-thumbnail.com",
|
|
"variants": [
|
|
"5f4cf81a2ac41700211f6e63"
|
|
],
|
|
"published": false,
|
|
"title": "Line Item",
|
|
"options": [
|
|
{
|
|
"values": [],
|
|
"_id": "5f4cf81a2ac41700211f6e62",
|
|
"title": "Size"
|
|
}
|
|
]
|
|
},
|
|
"quantity": 1
|
|
}
|
|
}
|
|
],
|
|
"discounts": [],
|
|
"payment_sessions": [],
|
|
"shipping_methods": [],
|
|
"shipping_total": 0,
|
|
"discount_total": 0,
|
|
"tax_total": 0,
|
|
"subtotal": 303.2,
|
|
"total": 303.2,
|
|
"region": {
|
|
"_id": "5f4cd57a5d1e3200214c0e4e",
|
|
"tax_rate": 0,
|
|
"countries": [
|
|
"US"
|
|
],
|
|
"payment_providers": [
|
|
"stripe"
|
|
],
|
|
"fulfillment_providers": [
|
|
"shiphero"
|
|
],
|
|
"name": "United States",
|
|
"currency_code": "EUR",
|
|
"tax_code": "ABR"
|
|
}
|
|
}
|
|
}
|