Skip to main content
API docs by Redocly

Shopping API (v0)

Download OpenAPI specification:Download

Create cart

Creates a new cart. Use this method to create an order, or to create a return. Its state is automatically set to draft. If you have enabled the mixed cart feature, you should set the fulfillment_group property for each product of the cart. It defines whether the product is to be shipped or picked up in store. To update the content of the cart, use the Update cart method.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
(Array of objects or objects) or (any or null)

Describes returned items if any.

state
string (Order state)
Enum: "draft" "ready" "placed" "accepted" "failed"

Desired state of the order. Use 'draft' while patching the order, use 'placed' to make an attempt to place the order.

shop
string or null <= 128 characters

The shop containing the items of the order.

shop_locale
string or null <= 128 characters

The locale used for the shop, in RFC 5646.

(any or null) or object

Personal information about the customer.

tax_exempt
boolean
Default: false

If true, the order is tax exempt.

object or (any or null)

Billing address. If not set, the shipping address will be used.

store_id
string <= 256 characters

ID of the store where this order was placed.

object or (any or null)

Manual order level price adjustments and coupons.

(any or null) or Array of objects

Attributes set by the tenant to be carried over to the export APIs without affecting the business logic of the NewStore platform.

(any or null) or object

Information about the source of the order.

(any or null) or Array of objects

The list of products contained in the order.

payments
object

Payment data blocks, each has the identifier provided as the key. The identifier depends on the 'type' property of the payment. When type is 'token', use the payment token. When type is 'authorized', use the charge identifier. When type is 'captured', use the capture identifier. Payments can be modified by these identifiers. Payment statuses are reported per identifier.

object or (any or null)

Shipping address.

object or (any or null)

Describes if the order needs an approval, before it is placed.

associate_id
string or null <= 256 characters

ID of the store associate who processed this order.

string or (any or null)

The currency for all the prices contained within this payload.

Responses

Request samples

Content type
application/json
{
  • "returns": [
    ],
  • "state": "draft",
  • "shop": "string",
  • "shop_locale": "string",
  • "customer": { },
  • "tax_exempt": false,
  • "billing_address": {
    },
  • "store_id": "string",
  • "price_modifiers": {
    },
  • "extended_attributes": { },
  • "channel": { },
  • "products": { },
  • "payments": { },
  • "shipping_address": {
    },
  • "manager_approval": {
    },
  • "associate_id": "string",
  • "currency": "string"
}

Response samples

Content type
application/json
{
  • "schema": {
    }
}

Get cart by id

Retrieves the specified cart.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

UUID-like identifier for the cart. The id is returned when you call the Create cart method.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "messages": [
    ],
  • "exchange": {
    },
  • "payment_statuses": { },
  • "totals": {
    },
  • "remaining_amount": 0,
  • "discounts": { },
  • "return_status": {
    },
  • "manager_approval": {
    },
  • "fiscal_cashbox_id": "string",
  • "tax_exemption_class": "string",
  • "tax_exemption_number": "string"
}

Update cart

Updates an existing cart. Use this method to update the status of the cart or to add items, payments, or a shipping method to the cart in order to place an order, return items or exchange items.

This method is also a way to ensure synchronization with the backend. For example, if you request a state change from ready to draft, the backend will reject the state change if your order still matches all criteria to be ready.

Note: You can call this method with an empty body to get the status of the payment(s).

Limitations:

  • An order can only contain one shipping address and one billing address.
  • At most 100 items per order are allowed.
  • At most 10 payments can be provided per order.
  • At most 100 extended attributes can be provided per order.
  • At most one discount coupon can be applied per order.
  • At most one manual order-level adjustment can be applied per order.
  • At most one manual item-level adjustment can be applied per item.

However, a coupon as well as a manual price adjustment can be applied together on the same order, even if both result in an order-level discount or an item-level discount (also if both discounts are applied on the same item). Related resources:

  • Use the Orders resource to retrieve the identifiers of the order and items to return.
  • Use the User configuration resource to retrieve the configured return reasons, item conditions, and their corresponding codes.
Authorizations:
newStoreAccessToken
path Parameters
id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

UUID-like identifier for the cart. The id is returned when you call the Create cart method.

Request Body schema: application/json
(Array of objects or objects) or (any or null)

Describes returned items if any.

state
string (Order state)
Enum: "draft" "ready" "placed" "accepted" "failed"

Desired state of the order. Use 'draft' while patching the order, use 'placed' to make an attempt to place the order.

shop
string or null <= 128 characters

The shop containing the items of the order.

shop_locale
string or null <= 128 characters

The locale used for the shop, in RFC 5646.

(any or null) or object

Personal information about the customer.

tax_exempt
boolean
Default: false

If true, the order is tax exempt.

object or (any or null)

Billing address. If not set, the shipping address will be used.

store_id
string <= 256 characters

ID of the store where this order was placed.

object or (any or null)

Manual order level price adjustments and coupons.

(any or null) or Array of objects

Attributes set by the tenant to be carried over to the export APIs without affecting the business logic of the NewStore platform.

(any or null) or object

Information about the source of the order.

(any or null) or Array of objects

The list of products contained in the order.

payments
object

Payment data blocks, each has the identifier provided as the key. The identifier depends on the 'type' property of the payment. When type is 'token', use the payment token. When type is 'authorized', use the charge identifier. When type is 'captured', use the capture identifier. Payments can be modified by these identifiers. Payment statuses are reported per identifier.

object or (any or null)

Shipping address.

object or (any or null)

Describes if the order needs an approval, before it is placed.

associate_id
string or null <= 256 characters

ID of the store associate who processed this order.

string or (any or null)

The currency for all the prices contained within this payload.

shipping_solution_id
string or null <= 64 characters

Identifies shipping solution for the order. Can be 'in_store_handover' when no shipping is required or one of the identifiers returned by the /order/{id}/shipping_solutions endpoint.

Responses

Request samples

Content type
application/json
{
  • "returns": [
    ],
  • "state": "draft",
  • "shop": "string",
  • "shop_locale": "string",
  • "customer": { },
  • "tax_exempt": false,
  • "billing_address": {
    },
  • "store_id": "string",
  • "price_modifiers": {
    },
  • "extended_attributes": { },
  • "channel": { },
  • "products": { },
  • "payments": { },
  • "shipping_address": {
    },
  • "manager_approval": {
    },
  • "associate_id": "string",
  • "currency": "string",
  • "shipping_solution_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "messages": [
    ],
  • "exchange": {
    },
  • "payment_statuses": { },
  • "totals": {
    },
  • "remaining_amount": 0,
  • "discounts": { },
  • "return_status": {
    },
  • "manager_approval": {
    },
  • "fiscal_cashbox_id": "string",
  • "tax_exemption_class": "string",
  • "tax_exemption_number": "string"
}

Generate cart token

Generates a cart token that can be exposed to external parties. A cart token is the encrypted order identifier. It can be exposed in public APIs when authentication is not an option but the order identifier is needed.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

UUID-like identifier for the cart. The id is returned when you call the Create cart method.

Responses

Response samples

Content type
application/json
{
  • "schema": {
    }
}

Get shipping solutions

Generates shipping solutions for the order. If there are any shipping discounts on the order, they will be applied to the shipping solutions. Tax is not calculated on the shipping solution generation. The tax is only calculated when the shipping solution is added to the order.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

UUID-like identifier for the cart. The id is returned when you call the Create cart method.

Responses

Response samples

Content type
application/json
{
  • "shipping_solutions": { }
}

Get document

Retrieves the document related to the provided cart id.

The type of document you get depends on the what the cart was used for:

  • A cart used to place an order: you retrieve a sales receipt.
  • A cart used for a return, you retrieve a refund note.
  • A cart used to exchange some items, you retrieve an exchange receipt.
Authorizations:
newStoreAccessToken
path Parameters
id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

UUID-like identifier for the cart. The id is returned when you call the Create cart method.

Responses

Response samples

Content type
application/json
{}

Send document

Sends the document related to the provided cart id to the provided email address.

The type of document depends on the what the cart was used for:

  • A cart used to place an order: a sales receipt is sent.
  • A cart used for a return, a refund note is sent.
  • A cart used to exchange some items, an exchange receipt is sent.
Authorizations:
newStoreAccessToken
path Parameters
id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

UUID-like identifier for the cart. The id is returned when you call the Create cart method.

Request Body schema: application/json
email
required
string

The email address the document is sent to.

force_send
boolean

If it is set to true, the email would be sent even if it was sent before.

Responses

Request samples

Content type
application/json
{
  • "schema": {
    }
}

Response samples

Content type
application/json
{
  • "schema": {
    }
}