350 lines
11 KiB
YAML
350 lines
11 KiB
YAML
title: Carts
|
|
domain: store
|
|
routes:
|
|
- method: GET
|
|
path: /carts/:id
|
|
- method: POST
|
|
path: /carts
|
|
- method: POST
|
|
path: /carts/:id
|
|
- method: POST
|
|
path: /carts/:id/complete-cart
|
|
- method: POST
|
|
path: /carts/:id/line-items
|
|
- method: POST
|
|
path: /carts/:id/line-items/:line_id
|
|
- method: POST
|
|
path: /carts/:id/payment-sessions
|
|
- method: POST
|
|
path: /carts/:id/payment-session/update
|
|
- method: POST
|
|
path: /carts/:id/payment-sessions/:provider_id/refresh
|
|
- method: POST
|
|
path: /carts/:id/payment-session
|
|
- method: POST
|
|
path: /carts/:id/shipping-methods
|
|
- method: DELETE
|
|
path: /carts/:id/payment-sessions/:provider_id
|
|
- method: DELETE
|
|
path: /carts/:id/line-items/:line_id
|
|
- 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 `variant_id` 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
|
|
description: >
|
|
Retrieves an existing cart.
|
|
- path: /:id
|
|
method: POST
|
|
title: Update a 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.
|
|
- name: customer_id
|
|
type: String
|
|
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/complete-cart
|
|
method: POST
|
|
title: Complete cart
|
|
description: >
|
|
Completes a cart. The following steps will be performed. Payment authorization
|
|
is attempted and if more work is required, we simply return the cart for further updates.
|
|
If payment is authorized and order is not yet created, we make sure to do so.
|
|
The completion of a cart can be performed idempotently with a provided header `Idempotency-Key`.
|
|
If not provided, we will generate one for the request.
|
|
- path: /:id/line-items
|
|
method: POST
|
|
title: Add line item
|
|
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
|
|
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
|
|
description: >
|
|
Removes a the given line item from the cart.
|
|
- path: /:id/discounts/:code
|
|
method: DELETE
|
|
title: Remove discount code
|
|
description: Removes a discount code from the cart.
|
|
- path: /:id/payment-sessions
|
|
method: POST
|
|
title: Create payment sessions
|
|
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
|
|
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-session
|
|
method: POST
|
|
title: Set payment session on cart
|
|
params:
|
|
- name: provider_id
|
|
type: String
|
|
required: true
|
|
description: Id of the provider (e.g. stripe).
|
|
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/payment-session/update
|
|
method: POST
|
|
title: Update payment session on cart
|
|
params:
|
|
- name: session
|
|
type: Dictionary
|
|
required: true
|
|
description: >
|
|
The session object needs to have a `provider_id` (e.g. stripe) and `data`, that holds the update data for the session.
|
|
The data object can be anything that might be needed for the payment provider 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: >
|
|
Updates the payment session 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
|
|
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": "cart_1234",
|
|
"email": null,
|
|
"billing_address_id": null,
|
|
"billing_address": null,
|
|
"shipping_address_id": "addr_1234",
|
|
"shipping_address": {
|
|
"id": "addr_1234",
|
|
"customer_id": null,
|
|
"company": null,
|
|
"first_name": null,
|
|
"last_name": null,
|
|
"address_1": null,
|
|
"address_2": null,
|
|
"city": null,
|
|
"country_code": "dk",
|
|
"province": null,
|
|
"postal_code": null,
|
|
"phone": null,
|
|
"created_at": "2021-02-04T15:40:54.691Z",
|
|
"updated_at": "2021-02-04T15:40:54.691Z",
|
|
"deleted_at": null,
|
|
"metadata": null
|
|
},
|
|
"items": [{
|
|
"id": "item_1234",
|
|
"cart_id": "cart_1234",
|
|
"order_id": null,
|
|
"swap_id": null,
|
|
"claim_order_id": null,
|
|
"title": "Terry Towel",
|
|
"description": "30x30",
|
|
"thumbnail": "",
|
|
"is_giftcard": false,
|
|
"should_merge": true,
|
|
"allow_discounts": true,
|
|
"has_shipping": false,
|
|
"unit_price": 6000,
|
|
"variant_id": "variant_1234",
|
|
"variant": {
|
|
"id": "variant_1234",
|
|
"title": "30x30",
|
|
"product_id": "prod_1234",
|
|
"sku": null,
|
|
"barcode": null,
|
|
"ean": null,
|
|
"upc": null,
|
|
"inventory_quantity": 9999,
|
|
"allow_backorder": false,
|
|
"manage_inventory": true,
|
|
"hs_code": null,
|
|
"origin_country": null,
|
|
"mid_code": null,
|
|
"material": null,
|
|
"weight": null,
|
|
"length": null,
|
|
"height": null,
|
|
"width": null,
|
|
"created_at": "2021-01-19T17:09:01.864Z",
|
|
"updated_at": "2021-02-02T02:43:17.718Z",
|
|
"deleted_at": null,
|
|
"metadata": null
|
|
},
|
|
"quantity": 1,
|
|
"fulfilled_quantity": null,
|
|
"returned_quantity": null,
|
|
"shipped_quantity": null,
|
|
"created_at": "2021-02-04T15:42:12.514Z",
|
|
"updated_at": "2021-02-04T15:42:12.514Z",
|
|
"metadata": {}
|
|
}],
|
|
"region_id": "reg_1234",
|
|
"region": {
|
|
"id": "reg_1234",
|
|
"name": "Denmark",
|
|
"currency_code": "dkk",
|
|
"tax_rate": "25",
|
|
"tax_code": null,
|
|
"countries": [{
|
|
"id": 60,
|
|
"iso_2": "dk",
|
|
"iso_3": "dnk",
|
|
"num_code": 208,
|
|
"name": "DENMARK",
|
|
"display_name": "Denmark",
|
|
"region_id": "reg_1234"
|
|
}],
|
|
"payment_providers": [{
|
|
"id": "stripe",
|
|
"is_installed": true
|
|
}],
|
|
"fulfillment_providers": [{
|
|
"id": "manual",
|
|
"is_installed": true
|
|
}],
|
|
"created_at": "2021-01-19T17:09:01.864Z",
|
|
"updated_at": "2021-01-21T15:44:05.492Z",
|
|
"deleted_at": null,
|
|
"metadata": null
|
|
},
|
|
"discounts": [],
|
|
"gift_cards": [],
|
|
"customer_id": null,
|
|
"payment_sessions": [{
|
|
"id": "ps_1234",
|
|
"cart_id": "cart_1234",
|
|
"provider_id": "stripe",
|
|
"is_selected": true,
|
|
"status": "pending",
|
|
"data": {},
|
|
"created_at": "2021-02-08T11:37:17.906Z",
|
|
"updated_at": "2021-02-08T11:37:17.906Z",
|
|
"idempotency_key": null
|
|
}],
|
|
"payment_id": null,
|
|
"payment": null,
|
|
"shipping_methods": [],
|
|
"type": "default",
|
|
"completed_at": null,
|
|
"created_at": "2021-02-04T15:40:54.691Z",
|
|
"updated_at": "2021-02-04T15:40:54.691Z",
|
|
"deleted_at": null,
|
|
"metadata": null,
|
|
"idempotency_key": null,
|
|
"payment_session": {
|
|
"id": "ps_1234",
|
|
"cart_id": "cart_1234",
|
|
"provider_id": "stripe",
|
|
"is_selected": true,
|
|
"status": "pending",
|
|
"data": {},
|
|
"created_at": "2021-02-08T11:37:17.906Z",
|
|
"updated_at": "2021-02-08T11:37:17.906Z",
|
|
"idempotency_key": null
|
|
},
|
|
"shipping_total": 0,
|
|
"discount_total": 0,
|
|
"tax_total": 1500,
|
|
"gift_card_total": 0,
|
|
"subtotal": 6000,
|
|
"total": 7500
|
|
}
|
|
}
|