---
schema_version: "1"
id: ef84ed453d881b11b5a8a28ecbaa8bb99905722bf36da797c655fbd1c632d4b1
title: Orders
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/orders.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/orders
source_site: developer.salesforce.com
content_type: documentation
content_hash: 9fb88f773fee7da9d2a2458dff4eaaf770742ab32364459e9436425afb068bfb
products:
  - B2C Commerce API
  - Salesforce APIs
---
Orders

# Orders

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/orders/orders-oas-v1-public.yaml)

## API Overview

Use the Orders API to update order status and order payment status, edit shipping addresses and custom order properties, manage order payment instruments, and get order information.

### Authentication & Authorization

The client requesting the order information must have access to the Orders resource. The API requests pass a system-to-system bearer token in the header of the request. The `POST /orders` endpoint uses the [ShopperTokenTsob](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=security%3AShopperTokenTsob) security scheme.

You must include `sfcc.orders` or `sfcc.orders.rw` in the client ID used to generate the OAuth token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

#### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Update Order Statuses

An order uses several status properties to define its workflow state. Some of them are used to trigger internal processes, such as inventory allocation. Others have no default function, but are available for use with customizations.

##### Order Status

The Order status reflects the overall status of the order. Transitions between order statuses trigger actions such as invoice generation and release of inventory reservations.

Order status can have one of the following values:

*   `created` - Default value; denotes that the order was created in the system but is not yet placed.
*   `new` - Set this value to place the order. When you set this value, the system generates shipment and invoice numbers. After the order is placed, you can’t change the order status to `created` or `failed`.
*   `failed` - Set this value to fail the order, for example, when you reject the order or when its payment fails. When you set this value, the system releases the order’s inventory reservations and removes any coupon redemptions. You can only set this value if the current order status is `created`. If you change the order status from `failed` to `created`, the system tries to revert the actions taken when it was set to `failed`. If inventory isn’t available, the reversion can fail.
*   `failed_with_reopen` - Set this value to fail the order and reopen the basket, if applicable. The order status is set to `failed`.
*   `completed` - Set this value to mark the order as complete, based on your business process, for example: when the order is fully paid, exported, and shipped.
*   `cancelled` - Set this value to cancel the order, for example: when the shopper requests it. When you set this value, the system releases the order’s inventory reservations, restores any wishlist items, and removes any coupon redemptions. If you change the order status from `cancelled` to `completed` or `new`, the system tries to revert the actions taken when it was set to `cancelled`. If inventory isn’t available, the reversion can fail.

##### Confirmation Status

An order confirmation is a document the vendor sends to the shopper. It confirms that the order has been received and accepted. You can use confirmation status to reflect the state of the document, or for other customizations. This field is provided for use in customizations. It isn’t associated with any default functionality.

Confirmation status can have one of the following values:

*   `not_confirmed` - Default value.
*   `confirmed` - Set this value when the order confirmation is sent to the shopper.

##### Export Status

After an order is placed, it must be fulfilled. If your process includes an external fulfillment system, such as a Warehouse Management System, you can use export status to manage the export of order data to the external system. For example, after using the GET /orders endpoint to get order data to export, set the order’s export status to `exported`. When identifying orders to export, your query can include orders with export status `ready` and exclude orders with export status `exported`.

Export status can have one of the following values:

*   `not_exported` - Default value.
*   `ready` - (custom purpose) Set this value when the order is ready for export.
*   `exported` - Set this value when the order has been exported. When you set this value, the system finalizes the order’s inventory transactions.
*   `failed` - (custom purpose) Set this value when the order export fails.

##### External Status

The external status field can hold any string value. For example, you can use it for values related to an external fulfillment system. This field is provided for use in customizations, and isn’t associated with any default functionality.

##### Payment Status

Use payment status to denote whether an order is partially or fully paid. This field is provided for use in customizations, and isn’t associated with any default functionality.

Payment status can have one of the following values:

*   `not_paid` - Default value.
*   `part_paid` - Set this value when the order is partially paid.
*   `paid` - Set this value when the order is fully paid.

##### Shipping Status

Use shipping status to denote whether an order is partially or fully shipped. This field is provided for use in customizations, and isn’t associated with any default functionality.

Shipping status can have one of the following values:

*   `not_shipped` - Default value.
*   `part_shipped` - Set this value when the order is partially shipped.
*   `shipped` - Set this value when the order is fully shipped.

Example scenarios:

*   After a successful fraud check and payment authorization, set the order status to `new`.
*   After a failed fraud check or payment authorization, set the order status to `failed`.
*   After an order’s information is exported to the warehouse system, set the export status to `exported`.
*   After the warehouse ships an order, set the shipping status to `shipped`.

#### Change Shipping Address

Use the Orders API to update the shipping address on an order.

For example, a shopper places an order, and then sends a request to change the shipping address on that order.

#### Get Order Data

Use the Orders API system-to-system integration use cases for order retrieval, reporting, dashboards, and so on. You can get information about a single order by specifying the order number, or get information about multiple orders by searching with attribute filters.

You can use the following attribute filters:

*   order status
*   export status
*   external status
*   confirmation status
*   payment status
*   shipping status
*   creation date to/from
*   last modified date to/from
*   offset
*   limit

You can sort the results in ascending or descending order using the following attributes (default: descending):

*   creation date
*   last modified date

#### Create Orders

Use the createOrders endpoint to create orders from a third-party system, such as a social media platform. Before using the endpoint, you must first complete the checkout process: apply all sanity checks, reserve inventory, authorize payment, apply promotions, and calculate the full cost of the order. Orders made by third-party systems are treated the same as orders made directly through the B2C Commerce platform, including how status updates and exports are handled.

#### Update Orders

Use the updateOrder endpoint to make changes to custom order attributes.

### Related APIs

*   [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) — Create orders from baskets during the checkout flow.

**Version:** 1.6.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.orders: Scope granting read access to order endpoints
    *   Scope sfcc.orders.rw: Scope granting read and write access to order endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
*   `ShopperTokenTsob` (oauth2) `ShopperTokenTsob` (TSOB = trusted system on behalf) is a child of the `ShopperToken` security scheme and extends the functionality of `ShopperToken` for specific use cases. A token of type `ShopperTokenTsob` allows you to access Shopper API endpoints, including OCAPI and B2C Commerce API for headless applications. Other than endpoints that require this specific subtype, you can access all other endpoints secured by the `ShopperToken` parent scheme with a `ShopperTokenTsob`. To learn how to get a `ShopperTokenTsob` token, see [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:getTrustedSystemAccessToken).
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/trusted-system/token)
    *   Scope sfcc.orders: Scope granting read access to order endpoints
    *   Scope sfcc.orders.rw: Scope granting read and write access to order endpoints

## Operations

### GET Return order details that match the query filters. By default, calling this API with no filter returns the 100 most recently created orders. To return up to 200 orders, use the limit parameter. To return a page of results past the first page, use a resource offset. \*Note\* : The sum of the offset and limit parameters cannot be greater than 10000.

`GET /organizations/{organizationId}/orders`

Operation ID: `getOrders`. Security: AmOAuth2 (sfcc.orders, sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `sortBy` (query, string) Sort results by creation date or last modified date. The default is creation date.  
    Allowed values: `creation_date`, `last_modified_date`. Default: `creation_date`.
*   `sortOrder` (query, string) Sort results in ascending or descending order. The default is descending.  
    Allowed values: `asc`, `desc`. Default: `desc`.
*   `status` (query, string) Filter results by status. Valid statuses are 'new', 'completed', and 'cancelled'. You can include up to two statuses as a comma-separated string.
*   `exportStatus` (query, array of object, style: form, explode: false) Filter results by export status. Valid export statuses are 'not\_exported', 'exported', 'ready', and 'failed'. You can include up to three export statuses as a comma-separated string.  
    Maximum items: 3.
    
    _Example_
    
    ```
    not_exported,ready,failed
    ```
    
    _Example_
    
    ```
    [
      "not_exported",
      "ready",
      "failed"
    ]
    ```
    
*   `externalStatus` (query, string) Filter results by external status.
*   `confirmationStatus` (query, string) Filter results by confirmation status. Valid confirmation statuses are 'confirmed' and 'not\_confirmed'.
    
    The order confirmation status.
    
      
    Allowed values: `confirmed`, `not_confirmed`. Example: `confirmed`.
*   `paymentStatus` (query, array of object, style: form, explode: false) Filter results by payment status. Valid payment statuses are 'not\_paid', 'part\_paid', and 'paid'. You can include up to two payment statuses as a comma-separated string.  
    Maximum items: 3.
    
    _Example_
    
    ```
    not_paid,part_paid
    ```
    
    _Example_
    
    ```
    [
      "not_paid",
      "part_paid"
    ]
    ```
    
*   `shippingStatus` (query, array of object, style: form, explode: false) Filter results by shipping status. Valid shipping statuses are 'not\_shipped', 'part\_shipped', and 'shipped'. You can include up to two shipping statuses as a comma-separated string.  
    Maximum items: 3.
    
    _Example_
    
    ```
    not_shipped,part_shipped
    ```
    
    _Example_
    
    ```
    [
      "not_shipped",
      "part_shipped"
    ]
    ```
    
*   `creationDateFrom` (query, string (date-time)) If passed, will return records where the `creationDate` is equal to or greater than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `creationDateTo` (query, string (date-time)) If passed, will return records where the `creationDate` is less than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModifiedDateFrom` (query, string (date-time)) If passed, will return records where the `lastModifiedDate` is equal to or greater than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModifiedDateTo` (query, string (date-time)) If passed, will return records where the `lastModifiedDate` is less than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 100.  
    Default: `100`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Order details returned successfully.
    
    Media type: `application/json`. Schema: `OrdersResponse`.
    
    _Example: Order_
    
    ```
    {
      "data": [
        {
          "adjustedMerchandizeTotalTax": 4.95,
          "adjustedShippingTotalTax": 0.3,
          "billingAddress": {
            "address1": "45 Main Rd.",
            "city": "Burlington",
            "countryCode": "US",
            "firstName": "Max",
            "fullName": "Max Mustermann",
            "lastName": "Mustermann",
            "phone": "6175555555",
            "postalCode": "05408",
            "stateCode": "MA"
          },
          "confirmationStatus": "confirmed",
          "createdBy": "storefront",
          "creationDate": "2015-05-19T15:23:18.000Z",
          "currency": "USD",
          "customerInfo": {
            "customerId": "abMKqMaNYOBMnNdDNzyC5oNTi5",
            "customerName": "Max Mustermann",
            "customerNo": "0002352",
            "email": "no-reply@salesforce.com",
            "guest": true
          },
          "customerLocale": "en_US",
          "exportStatus": "not_exported",
          "invoiceNo": "00000001",
          "lastModified": "2020-11-04T14:13:31.061Z",
          "merchandizeTotalTax": 4.95,
          "orderNo": "00000410",
          "orderTotal": 110.24,
          "paymentInstruments": [
            {
              "paymentCard": {
                "cardType": "Visa",
                "creditCardExpired": true,
                "expirationMonth": 1,
                "expirationYear": 2020,
                "holder": "Max Mustermann",
                "maskedNumber": "***************1111",
                "numberLastDigits": "1111",
                "validFromMonth": 1,
                "validFromYear": 2018
              },
              "paymentInstrumentId": "21052ad719a076cdc83637851e",
              "paymentMethodId": "CREDIT_CARD",
              "paymentTransaction": {
                "amount": 110.24,
                "transactionId": "40f07907428e23c4bbc6fb0446",
                "c_authResult": "AUTHORIZED"
              },
              "c_issuerBank": "JPMORGAN CHASE BANK, N.A."
            }
          ],
          "paymentStatus": "not_paid",
          "placeDate": "2015-05-19T15:23:18.000Z",
          "productItems": [
            {
              "adjustedTax": 4.95,
              "basePrice": 99,
              "bonusProductLineItem": false,
              "gift": false,
              "grossPrice": 103.95,
              "itemId": "99e96c7f8b46b98de2bae5d778",
              "itemText": "Flat Front Pant",
              "netPrice": 99,
              "position": 1,
              "priceAfterItemDiscount": 99,
              "priceAfterOrderDiscount": 99,
              "productId": "701643632930",
              "productName": "Flat Front Pant",
              "quantity": 1,
              "shipmentId": "me",
              "tax": 4.95,
              "taxBasis": 99,
              "taxRate": 0.05
            }
          ],
          "productSubTotal": 99,
          "productTotal": 99,
          "remoteHost": "127.0.0.1",
          "shipments": [
            {
              "adjustedMerchandizeTotalTax": 4.95,
              "adjustedShippingTotalTax": 0.3,
              "gift": false,
              "merchandizeTotalTax": 99,
              "productSubTotal": 99,
              "productTotal": 99,
              "shipmentId": "me",
              "shipmentNo": "00000001",
              "shipmentTotal": 110.24,
              "shippingAddress": {
                "address1": "45 Main Rd.",
                "city": "Burlington",
                "countryCode": "US",
                "firstName": "Max",
                "fullName": "Max Mustermann",
                "lastName": "Mustermann",
                "phone": "6175555555",
                "postalCode": "05408",
                "stateCode": "MA"
              },
              "shippingMethod": {
                "id": "DefaultShippingMethod"
              },
              "shippingStatus": "not_shipped",
              "shippingTotal": 5.99,
              "shippingTotalTax": 0.3,
              "taxTotal": 5.25
            }
          ],
          "shippingItems": [
            {
              "adjustedTax": 0.3,
              "basePrice": 5.99,
              "grossPrice": 6.29,
              "itemId": "23ace383d9355c881f1c00417a",
              "itemText": "Shipping",
              "netPrice": 5.99,
              "priceAfterItemDiscount": 5.99,
              "shipmentId": "me",
              "tax": 0.3,
              "taxBasis": 5.99,
              "taxRate": 0.05,
              "type": "fixed_price"
            }
          ],
          "shippingStatus": "not_shipped",
          "shippingTotal": 5.99,
          "shippingTotalTax": 0.3,
          "siteId": "ShoppingSite",
          "status": "new",
          "taxation": "net",
          "taxTotal": 5.25
        }
      ]
    }
    ```
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### POST Create an order.

`POST /organizations/{organizationId}/orders`

Operation ID: `createOrders`. Security: ShopperTokenTsob (sfcc.orders.rw).

Use this endpoint whenever a fully calculated and paid or authorized order is created in any third-party system.

The endpoint can create an order on-the-fly in the Commerce Cloud platform by passing the order as JSON payload in the body of the POST request.

Other than the Basket API, this endpoint decouples any relation to other system domains, such as:

*   Products
*   Inventory
*   Promotions
*   Gift certificates
*   Coupons

The order isn't treated differently than any other orders in the Commerce Cloud platform, including status updates and order exports.

**Note**: For the custom attribute to be available for orders, configure it in Business Manager for both Basket and Order objects.

**Important**: This endpoint uses the `ShopperTokenTsob` security scheme. Always check the Security section of the endpoint documentation, which, by default, is hidden.

### Preconditions

The checkout must happen before making a request to this endpoint. That means that all sanity checks _are_ applied, the inventory _is_ reserved, the payment _is_ authorized, and the Basket _is_ fully calculated (including all promotions).

After meeting these conditions, it's possible to create the order in the Commerce Cloud platform.

### Decoupling

This endpoint can create an order with unknown products, different pricing for known products, unplanned price-adjustments (unrelated to the system's configured promotions), and passing unknown payment and shipping methods.

**Note**: There's no lookup or calculation, even if the passed object is configured in the platform.

### Still Coupled

The endpoint is still coupled to:

*   the taxation policy (gross or net) specified in the site's preferences.
*   the passed currency, which must be defined in the site.

### Calculation

The platform does not perform multiplying or dividing operations on this order.

The following fields are summed during runtime on the platform:

**Order Level**

*   `adjustedMerchandizeTotalTax`
*   `adjustedShippingTotalTax`
*   `merchandizeTotalTax`
*   `adjustedTax`
*   `productSubTotal`
*   `productTotal`
*   `shippingTotalTax`
*   `orderTotal`
*   `taxTotal`

**Line Item Level**

*   `priceAfterItemDiscount`
*   `priceAfterOrderDiscount`
*   `adjustedTax`

**Shipment**

*   `merchandizeTotalTax`
*   `productSubTotal`
*   `productTotal`
*   `shippingTotalTax`

To make sure the fields are summed correctly, the passed `orderTotal` and `taxTotal` are compared to the platform's summed `orderTotal` and `taxTotal`.

An `InvalidOrderTotalException` or `InvalidTaxTotalException` is thrown if the calculation doesn't match.

The `orderTotal` and `taxTotal` are calculated as follows:

*   `orderTotal` = sum(`ProductLineItems.grossPrice`) + sum(`Shipments.shipmentTotal`) - sum(`ProductLineItems.PriceAdjustments.grossPrice` + `Order.PriceAdjustments.grossPrice`)
*   `taxTotal` = sum (`ProductLineItems.tax`) + sum(`Shipments.taxTotal`) - sum(`ProductLineItems.PriceAdjustments.tax` + `Order.PriceAdjustments.tax`)

### Order Status

The order is automatically placed after creation.

The payment status can be set via payload.

All other status can be set via PATCH `orders/{orderNo}/status`.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `CreateOrderRequest`.

_Example: minimalExample_

```
{
  "billingAddress": {
    "address1": "43 Main Rd.",
    "city": "Burlington",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "channelType": "instagramcommerce",
  "currency": "USD",
  "orderNo": "0000019373",
  "orderTotal": 66.91,
  "paymentInstruments": [
    {
      "paymentMethodId": "PAYPAL",
      "paymentTransaction": {
        "amount": 66.91,
        "transactionId": "abc13384ajsgdk1"
      }
    }
  ],
  "productItems": [
    {
      "basePrice": 30.98,
      "grossPrice": 61.96,
      "netPrice": 49.57,
      "productId": "black-shoe_29347-38",
      "productName": "special edition shoe women 38",
      "quantity": 2,
      "shipmentId": "shipment1",
      "tax": 12.39
    }
  ],
  "shipments": [
    {
      "shipmentId": "shipment1",
      "shippingAddress": {
        "address1": "43 Main Rd.",
        "city": "Burlington",
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "shippingMethod": "EXPRESS",
      "shippingTotal": 4.95,
      "taxTotal": 0
    }
  ],
  "taxTotal": 12.39
}
```

_Example: fullExample_

```
{
  "billingAddress": {
    "address1": "45 Main Rd.",
    "city": "Burlington",
    "countryCode": "US",
    "firstName": "John",
    "fullName": "John Doe",
    "jobTitle": "Product Manager",
    "lastName": "Doe",
    "phone": "6175555555",
    "postalCode": "01803-2336",
    "secondName": "Jr.",
    "stateCode": "MA",
    "suffix": "Jr.",
    "suite": "suite",
    "title": "M.Sc."
  },
  "businessType": "b2c",
  "channelType": "instagramcommerce",
  "currency": "USD",
  "customerLocale": "en_US",
  "orderNo": "00000041",
  "orderPriceAdjustments": [
    {
      "amount": 5,
      "basePrice": -6,
      "grossPrice": -6,
      "itemText": "5 off",
      "netPrice": -5,
      "reasonCode": "registered",
      "tax": -1,
      "taxBasis": 6
    }
  ],
  "orderTotal": 113.24,
  "paymentInstruments": [
    {
      "paymentMethodId": "CREDITCARD",
      "paymentTransaction": {
        "amount": 113.24,
        "transactionId": "abc13384ajsgdk1"
      }
    }
  ],
  "paymentStatus": "paid",
  "productItems": [
    {
      "basePrice": 99,
      "brand": "brand",
      "grossPrice": 103.95,
      "itemText": "Flat Front Pant",
      "netPrice": 99,
      "priceAdjustments": [
        {
          "amount": 5,
          "grossPrice": -6,
          "itemText": "5 off",
          "netPrice": -5,
          "reasonCode": "registered",
          "tax": -1
        }
      ],
      "productId": "701643632930",
      "productName": "Flat Front Pant",
      "quantity": 1,
      "shipmentId": "00000001",
      "tax": 4.95,
      "taxBasis": 99,
      "taxRate": 0.05
    }
  ],
  "shipments": [
    {
      "shipmentId": "00000001",
      "shippingAddress": {
        "address1": "45 Main Rd.",
        "address2": "road 2",
        "city": "Burlington",
        "companyName": "Salesforce",
        "countryCode": "US",
        "firstName": "John",
        "fullName": "John Doe",
        "jobTitle": "Product Manager",
        "lastName": "Doe",
        "phone": "6175555555",
        "postBox": "none",
        "postalCode": "01803-2336",
        "salutation": "Mr.",
        "stateCode": "MA",
        "suffix": "Jr.",
        "suite": "suite",
        "title": "M.Sc."
      },
      "shippingMethod": "EXPRESS",
      "shippingTotal": 21.29,
      "taxTotal": 4.95
    }
  ],
  "taxTotal": 7.9
}
```

_Example: multiShipmentExample_

```
{
  "billingAddress": {
    "address1": "43 Main Rd.",
    "city": "Burlington",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "channelType": "instagramcommerce",
  "currency": "USD",
  "orderNo": "000028376",
  "orderTotal": 75.86,
  "paymentInstruments": [
    {
      "paymentMethodId": "PAYPAL",
      "paymentTransaction": {
        "amount": 75.86,
        "transactionId": "abc13384ajsgdk1"
      }
    }
  ],
  "productItems": [
    {
      "basePrice": 30.98,
      "grossPrice": 30.98,
      "netPrice": 24.79,
      "productId": "black-shoe_081273-38",
      "productName": "special edition shoe women 38",
      "quantity": 1,
      "shipmentId": "shipment1",
      "tax": 6.19
    },
    {
      "basePrice": 30.98,
      "grossPrice": 30.98,
      "netPrice": 24.79,
      "productId": "red-shirt_2937298-xl",
      "productName": "t shirt XL",
      "quantity": 1,
      "shipmentId": "shipment2",
      "tax": 6.19
    }
  ],
  "shipments": [
    {
      "shipmentId": "shipment1",
      "shippingAddress": {
        "address1": "43 Main Rd.",
        "city": "Burlington",
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "shippingMethod": "GROUND",
      "shippingTotal": 4.95,
      "taxTotal": 0
    },
    {
      "shipmentId": "shipment2",
      "shippingAddress": {
        "address1": "45 Main Rd.",
        "city": "Burlington",
        "firstName": "John",
        "lastName": "Doe"
      },
      "shippingMethod": "EXPRESS",
      "shippingTotal": 8.95,
      "taxTotal": 0
    }
  ],
  "taxTotal": 12.38
}
```

_Example: fullPaymentInstrumentExample_

```
{
  "billingAddress": {
    "address1": "45 Main Rd.",
    "city": "Burlington",
    "firstName": "John",
    "lastName": "Doe"
  },
  "channelType": "instagramcommerce",
  "currency": "USD",
  "orderNo": "0000091837",
  "orderTotal": 66.91,
  "paymentInstruments": [
    {
      "paymentMethodId": "CREDITCARD",
      "paymentTransaction": {
        "amount": 30,
        "authorizationStatus": {
          "code": "0",
          "message": "credit card successfully authorized",
          "status": 0
        },
        "transactionId": "abc13384ajsgdk1"
      }
    },
    {
      "paymentMethodId": "PAYPAL",
      "paymentTransaction": {
        "amount": 36.91,
        "authorizationStatus": {
          "code": "0",
          "message": "paypal authorized",
          "status": 0
        },
        "transactionId": "abceou98463"
      }
    }
  ],
  "paymentStatus": "paid",
  "productItems": [
    {
      "basePrice": 30.98,
      "grossPrice": 61.96,
      "netPrice": 49.57,
      "productId": "black-shoe_97253-38",
      "productName": "special edition shoe women 38",
      "quantity": 2,
      "shipmentId": "shipment1",
      "tax": 12.39
    }
  ],
  "shipments": [
    {
      "shipmentId": "shipment1",
      "shippingAddress": {
        "address1": "45 Main Rd.",
        "city": "Burlington",
        "firstName": "John",
        "lastName": "Doe"
      },
      "shippingMethod": "GROUND",
      "shippingTotal": 4.95,
      "taxTotal": 0
    }
  ],
  "taxTotal": 12.39
}
```

#### Responses

*   **201** Order created successfully. No content returned.
    
    Headers:
    
    *   `Location` (string) The location for accessing the created order.
*   **400** The passed taxTotal is not equal to the calculated taxTotal.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidOrderTotal_
    
    ```
    {
      "title": "Invalid Order Total",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-order-total",
      "detail": "The passed order total '72.96' does not match the calculated order total '74.96'."
    }
    ```
    
    _Example: InvalidTaxTotal_
    
    ```
    {
      "title": "Invalid Tax Total",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-tax-total",
      "detail": "The passed tax total '2.95' does not match the calculated tax total '5.56'."
    }
    ```
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'."
    }
    ```
    
*   **404** The given shipment ID does not reference an existing shipment.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ShipmentNotFound_
    
    ```
    {
      "title": "Shipment Not Found,",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found,",
      "detail": "No shipment with ID 'express_shipment' could be found."
    }
    ```
    

### GET Return order details for the specified order number.

`GET /organizations/{organizationId}/orders/{orderNo}`

Operation ID: `getOrder`. Security: AmOAuth2 (sfcc.orders, sfcc.orders.rw).

#### Parameters

*   `orderNo` (path, OrderNo, required) The order number.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Order details returned successfully.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example: Order_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 4.95,
      "adjustedShippingTotalTax": 1.3,
      "billingAddress": {
        "address1": "45 Main Rd.",
        "city": "Burlington",
        "countryCode": "US",
        "firstName": "Max",
        "fullName": "Max Mustermann",
        "lastName": "Mustermann",
        "phone": "6175555555",
        "postalCode": "05408",
        "stateCode": "MA"
      },
      "confirmationStatus": "confirmed",
      "createdBy": "storefront",
      "creationDate": "2015-05-19T15:23:18.000Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "cdrjZ5iQeOQjpqKldaSzbvg2E8",
        "customerName": "Max Mustermann",
        "customerNo": "0002352",
        "email": "no-reply@salesforce.com",
        "guest": true
      },
      "customerLocale": "en_US",
      "exportStatus": "not_exported",
      "invoiceNo": "00000001",
      "lastModified": "2020-11-05T13:08:05.588Z",
      "merchandizeTotalTax": 4.95,
      "orderNo": "00000410",
      "orderTotal": 110.24,
      "paymentInstruments": [
        {
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": true,
            "expirationMonth": 1,
            "expirationYear": 2020,
            "holder": "Max Mustermann",
            "maskedNumber": "***************1111",
            "numberLastDigits": "1111",
            "validFromMonth": 1,
            "validFromYear": 2018
          },
          "paymentInstrumentId": "2c36f04e453a2512fba74ae1ea",
          "paymentMethodId": "CREDIT_CARD",
          "paymentTransaction": {
            "amount": 110.24,
            "transactionId": "40f07907428e23c4bbc6fb0446",
            "c_authResult": "AUTHORIZED"
          },
          "c_issuerBank": "JPMORGAN CHASE BANK, N.A."
        }
      ],
      "paymentStatus": "not_paid",
      "placeDate": "2015-05-19T15:23:18.000Z",
      "productItems": [
        {
          "adjustedTax": 4.95,
          "basePrice": 99,
          "bonusProductLineItem": false,
          "gift": false,
          "grossPrice": 103.95,
          "itemId": "3390171e44271bad9c36592049",
          "itemText": "Flat Front Pant",
          "netPrice": 99,
          "position": 1,
          "priceAfterItemDiscount": 99,
          "priceAfterOrderDiscount": 99,
          "productId": "701643632930",
          "productName": "Flat Front Pant",
          "quantity": 1,
          "shipmentId": "me",
          "shippingItemId": "a46294cffd6945a511cb6fce05",
          "tax": 4.95,
          "taxBasis": 99,
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 99,
      "productTotal": 99,
      "remoteHost": "127.0.0.1",
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 4.95,
          "adjustedShippingTotalTax": 1.3,
          "gift": false,
          "merchandizeTotalTax": 99,
          "productSubTotal": 99,
          "productTotal": 99,
          "shipmentId": "me",
          "shipmentNo": "00000001",
          "shipmentTotal": 110.24,
          "shippingAddress": {
            "address1": "45 Main Rd.",
            "city": "Burlington",
            "countryCode": "US",
            "firstName": "Max",
            "fullName": "Max Mustermann",
            "lastName": "Mustermann",
            "phone": "6175555555",
            "postalCode": "05408",
            "stateCode": "MA"
          },
          "shippingMethod": {
            "id": "DefaultShippingMethod"
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 25.99,
          "shippingTotalTax": 1.3,
          "taxTotal": 5.25
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.3,
          "basePrice": 5.99,
          "grossPrice": 6.29,
          "itemId": "4c3d46056d49226904ee61946c",
          "itemText": "Shipping",
          "netPrice": 5.99,
          "priceAfterItemDiscount": 5.99,
          "shipmentId": "me",
          "tax": 0.3,
          "taxBasis": 5.99,
          "taxRate": 0.05,
          "type": "fixed_price"
        },
        {
          "adjustedTax": 1,
          "basePrice": 10,
          "grossPrice": 21,
          "itemId": "a46294cffd6945a511cb6fce05",
          "itemText": "Item Shipping Cost (Surcharge)",
          "netPrice": 20,
          "priceAfterItemDiscount": 20,
          "shipmentId": "me",
          "tax": 1,
          "taxBasis": 20,
          "taxRate": 0.05,
          "type": "surcharge"
        }
      ],
      "shippingStatus": "not_shipped",
      "shippingTotal": 25.99,
      "shippingTotalTax": 1.3,
      "siteId": "ShoppingSite",
      "status": "new",
      "taxation": "net",
      "taxTotal": 5.25
    }
    ```
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PATCH Update an order.

`PATCH /organizations/{organizationId}/orders/{orderNo}`

Operation ID: `updateOrder`. Security: AmOAuth2 (sfcc.orders.rw); ShopperTokenTsob (sfcc.orders.rw).

#### Parameters

*   `orderNo` (path, OrderNo, required) The order number.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderUpdateRequest`.

_Example: OrderUpdateRequest_

```
{
  "c_carrierCode": "DHL",
  "c_weight": 2.4,
  "c_review": null
}
```

#### Responses

*   **204** Order updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order confirmation status.

`PUT /organizations/{organizationId}/orders/{orderNo}/confirmation-status`

Operation ID: `updateOrderConfirmationStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderConfirmationStatusUpdateRequest`.

_Example: OrderConfirmationStatusUpdate_

```
{
  "status": "confirmed"
}
```

#### Responses

*   **204** Order confirmation status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order export status. If on-order inventory is enabled for the associated inventory list, then setting the export status to EXPORTED finalizes on-order inventory transactions for this order by changing their type from on-order to final.

`PUT /organizations/{organizationId}/orders/{orderNo}/export-status`

Operation ID: `updateOrderExportStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderExportStatusUpdateRequest`.

_Example: OrderExportStatus_

```
{
  "status": "exported"
}
```

#### Responses

*   **204** Order export status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order external status.

`PUT /organizations/{organizationId}/orders/{orderNo}/external-status`

Operation ID: `updateOrderExternalStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderExternalStatusUpdateRequest`.

_Example: OrderExportStatus_

```
{
  "status": "external status"
}
```

#### Responses

*   **204** Order external status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order payment status.

`PUT /organizations/{organizationId}/orders/{orderNo}/payment-status`

Operation ID: `updateOrderPaymentStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderPaymentStatusUpdateRequest`.

_Example: PaymentStatus_

```
{
  "status": "paid"
}
```

#### Responses

*   **204** Order payment status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order shipping status.

`PUT /organizations/{organizationId}/orders/{orderNo}/shipping-status`

Operation ID: `updateOrderShippingStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderShippingStatusUpdateRequest`.

_Example: ShippingStatus_

```
{
  "status": "shipped"
}
```

#### Responses

*   **204** Order shipping status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### POST Submit a third-party OMS status event for an order.

`POST /organizations/{organizationId}/orders/{orderNo}/oms-status-events`

Operation ID: `createOmsStatusEvent`. Security: AmOAuth2 (sfcc.orders.rw).

Accepts a single fulfillment or adjustment event from an external OMS and forwards it to the configured order event subscribers. Exactly one of fulfillmentEvent or adjustment must be present. The event is processed asynchronously; the endpoint returns 202 Accepted once the event is validated and queued.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `OmsStatusEventRequest`.

_Example: OmsFulfillmentStatusEvent_

```
{
  "omsOrderId": "MAN-9988",
  "fulfillmentEvent": {
    "id": "ship-001",
    "occurredAt": "2026-06-03T10:15:00.000Z",
    "type": "shipped",
    "lineItems": [
      {
        "id": "pli-001",
        "quantity": 2
      },
      {
        "id": "pli-002",
        "quantity": 1
      }
    ],
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "carrier": "UPS",
    "description": "Handed to carrier"
  }
}
```

_Example: OmsAdjustmentStatusEvent_

```
{
  "omsOrderId": "MAN-9988",
  "adjustment": {
    "id": "ret-7788",
    "type": "return",
    "occurredAt": "2026-06-03T10:15:00.000Z",
    "status": "completed",
    "lineItems": [
      {
        "id": "pli-001",
        "quantity": -1
      }
    ],
    "totals": [
      {
        "type": "total",
        "amount": -1999,
        "displayText": "Refund"
      },
      {
        "type": "tax",
        "amount": -160
      }
    ],
    "description": "Customer requested — defective item"
  }
}
```

#### Responses

*   **202** The status event was accepted and queued for forwarding to order event subscribers. No content returned.
*   **400** The request body or path violates required syntax (for example, neither or both event objects present, or a required field/enum constraint is violated).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **409** Order Management (OMS) is not active for this site. The site does not have an OMS integration enabled, so the status event cannot be forwarded.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OmsNotActive_
    
    ```
    {
      "title": "Oms Not Active",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/oms-not-active",
      "detail": "Order Management (OMS) is not active for this site."
    }
    ```
    

### PUT Update order status.

`PUT /organizations/{organizationId}/orders/{orderNo}/status`

Operation ID: `updateOrderStatus`. Security: AmOAuth2 (sfcc.orders.rw).

Orders in status NEW, COMPLETED or CANCELLED can't be changed to status CREATED or FAILED.

Changing the status causes different actions on inventory, coupons, wishlists, and the order itself:

*   Fail Order: Release inventory and remove coupon redemptions. (CREATED -> FAILED)
*   Fail Order With Reopen Basket: Release inventory, remove coupon redemptions, and reopen the basket, if applicable. A basket can only be reopened if no other basket for the customer exists at the moment of failing the order since a customer is limited to 1 storefront basket. (CREATED -> FAILED)
*   Undo Fail Order: Reserve inventory and recreate coupon redemptions. (FAILED -> CREATED)
*   Place Order: Generate Shipment and invoice numbers. (CREATED -> NEW, COMPLETED or CANCELLED)
*   Cancel Order: Release inventory, remove wishlist purchases, and remove coupon redemptions. (NEW, COMPLETED -> CANCELLED)
*   Undo Cancel Order: Reserve inventory, add wishlist purchases, and recreate coupon redemptions. (CANCELLED -> NEW, COMPLETED)

Actions can fail, for example: when inventory is no longer available.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderStatusUpdateRequest`.

_Example: OrderStatus_

```
{
  "status": "new"
}
```

#### Responses

*   **201** Order status updated successfully. No content returned.
    
    Headers:
    
    *   `Location` (string) The location for accessing the reopened basket.
*   **204** Order status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    
*   **409** The failed order can't be reopened.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: UndoFailOrder_
    
    ```
    {
      "title": "Undo Fail Order",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/undo-fail-order",
      "detail": "The failed order with number '00020029’ cannot be reopened."
    }
    ```
    

### PATCH Update the payment instrument of an order.

`PATCH /organizations/{organizationId}/orders/{orderNo}/payment-instruments/{paymentInstrumentId}`

Operation ID: `updateOrderPaymentInstrument`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `paymentInstrumentId` (path, string, required) ID of the payment instrument.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `PaymentInstrumentUpdateRequest`.

_Example: OrderPaymentInstrument_

```
{
  "c_giftCardNumber": "12kH5DSkfsaErrRjKheWqqZ"
}
```

#### Responses

*   **204** Order payment instrument updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given payment instrument ID does not reference an existing payment instrument.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ShipmentNotFound: same as POST /organizations/{organizationId}/orders 404 response._
    

### PATCH Update the transaction of an order payment instrument.

`PATCH /organizations/{organizationId}/orders/{orderNo}/payment-instruments/{paymentInstrumentId}/transaction`

Operation ID: `updateOrderPaymentTransaction`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `paymentInstrumentId` (path, string, required) ID of the payment instrument.  
    Minimum length: 1.
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `PaymentTransactionUpdateRequest`.

_Example: OrderStatus_

```
{
  "c_externalReferenceCode": "dfg73DsFgH93Lkj2SaArePos",
  "c_processedDate": "2019-10-07",
  "c_additionalInformation": "Brunch enim ligula congue eu tempus craft beer tellus amet non urna sapien you probably haven’t heard of them eros ornare massa massa. Duis craft beer mattis pellentesque nulla risus arcu San Francisco adipiscing proin lorem sapien integer wire-rimmed glasses auctor ipsum cursus eget nam. Toms bibendum donec vivamus molestie vulputate fixie cursus amet eget nibh integer craft beer pellentesque odio mauris porttitor sodales."
}
```

#### Responses

*   **204** Payment instrument transaction updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given payment instrument ID does not reference an existing payment instrument.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ShipmentNotFound: same as POST /organizations/{organizationId}/orders 404 response._
    

### PUT Create or replace a shipping address.

`PUT /organizations/{organizationId}/orders/{orderNo}/shipments/{shipmentId}/shipping-address`

Operation ID: `updateOrderShippingAddress`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, string, required) ID of the shipment.  
    Minimum length: 1.
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `ShippingAddressUpdateRequest`.

_Example: Shipment_

```
{
  "address1": "100 Presidential Way",
  "address2": "100 Presidential Way 2",
  "city": "Woburn",
  "lastName": "Smith",
  "title": "Prof. Dr.",
  "countryCode": "US",
  "phone": "+1 123 456789",
  "companyName": "DWRE",
  "secondName": "Daniel",
  "salutation": "Mr.",
  "stateCode": "MA",
  "postalCode": "01801",
  "firstName": "John",
  "jobTitle": "Director",
  "c_district": "South End",
  "c_floor": 2,
  "c_note": "Engineering"
}
```

#### Responses

*   **204** Shipping address created or replaced successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given shipment ID does not reference an existing shipment.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ShipmentNotFound: same as POST /organizations/{organizationId}/orders 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### OrderExportStatus

The order export status.

Type: `string`.

Allowed values: `exported`, `not_exported`, `ready`, `failed`. Example: `exported`.

### OrderPaymentStatus

The order payment status.

Type: `string`.

Allowed values: `paid`, `part_paid`, `not_paid`. Example: `paid`.

### OrderShippingStatus

The order shipping status.

Type: `string`.

Allowed values: `shipped`, `part_shipped`, `not_shipped`. Example: `shipped`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### OrdersResponse

Document representing an orders result.

*   `data` (_array of Order_, required) The orders data.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CreateOrderRequest

Document representing the order create request.

*   `billingAddress` (_object_, required) The billing address. The name from the billing address is required and is used as the customer's name (for guest customer).
    
    Includes all fields of `Address`.
    
*   `businessType` (_string_) The business type.  
    Allowed values: `b2c`, `b2b`. Example: `b2c`.
*   `channelType` (_string_) The sales channel.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `instagramcommerce`.
*   `currency` (_CurrencyCode_, required)
*   `customerLocale` (_string_) The locale of the customer who created the order.  
    Maximum length: 256. Example: `en_US`.
*   `orderNo` (_object_) The order number. This must be unique in the site and is generated if no orderNo is passed in payload.  
    Example: `ORDER_000000001`.
    
    Includes all fields of `OrderNo`.
    
    Example: `ORDER_000000001`.
    
*   `orderPriceAdjustments` (_array of CreateOrderPriceAdjustment_) The order-level price adjustments.  
    Maximum items: 20.
*   `orderTotal` (_number (double)_, required) The total price, including products, shipping, and tax. If this value does not match the calculated value (sum of all grossPrices minus PriceAdjustments), an InvalidOrderTotalException is thrown.  
    Example: `39.27`.
*   `paymentInstruments` (_array of CreateOrderPaymentInstrument_, required) The payment instruments list.  
    Maximum items: 20.
*   `paymentStatus` (_string_) The payment status from the order.  
    Allowed values: `paid`, `not_paid`. Example: `paid`.
*   `productItems` (_array of CreateOrderProductItems_, required) The product items.  
    Minimum items: 1. Maximum items: 200.
*   `shipments` (_array of CreateOrderShipment_, required) The shipments.  
    Minimum items: 1. Maximum items: 10.
*   `taxTotal` (_number (double)_, required) The total tax amount.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderNo

The order number

Type: `string`.

Minimum length: 1. Maximum length: 50. Example: `00000410`.

### Order

Document representing an order.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the order, including price adjustments, but not including service charges such as shipping.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the order, including shipping price adjustments.  
    Example: `0.3`.
*   `affiliatePartnerId` (_string_) The affiliate partner ID.  
    Maximum length: 256. Example: `PARTNER_US_001`.
*   `affiliatePartnerName` (_string_) The affiliate partner name.  
    Maximum length: 256. Example: `PARTNER_US_001`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `Address`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `businessType` (_string_) The business type.  
    Allowed values: `b2c`, `b2b`. Example: `b2c`.
*   `cancelCode` (_string_) The cancellation code.  
    Maximum length: 256. Example: `canceled`.
*   `cancelDescription` (_string_) The cancellation description.  
    Maximum length: 4000. Example: `Ordered by mistake.`.
*   `channelType` (_string_) The sales channel.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `storefront`.
*   `confirmationStatus` (_OrderConfirmationStatus_)
*   `couponItems` (_array of CouponItem_) The coupon items.
*   `createdBy` (_string_) This value depends on how the order was created. If a shopper created the order, this value is Customer. If a job created the order, this value is System. Otherwise, this value is the name of the user who created the order.  
    Maximum length: 256. Example: `Customer`.
*   `creationDate` (_string (date-time)_) The timestamp when the order was created.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `customerLocale` (_string_) The locale of the customer who created the order.  
    Maximum length: 256. Example: `en_US`.
*   `currency` (_CurrencyCode_)
*   `customerInfo` (_CustomerInfo_)
*   `customerOrderReference` (_string_) The customer-specific reference information.  
    Maximum length: 256. Example: `REF_US_143`.
*   `exportStatus` (_OrderExportStatus_)
*   `externalOrderNo` (_string_) The external order number associated with the order.  
    Maximum length: 256. Example: `00000410`.
*   `externalOrderStatus` (_string_) The status from an external order associated with this order.  
    Maximum length: 256. Example: `Submitted`.
*   `externalOrderText` (_string_) The text from an external order associated with this order.  
    Maximum length: 4000. Example: `Order is being prepared`.
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items.
*   `globalPartyId` (_string_) The Customer 360 Global Party ID associated with the shopper.  
    Maximum length: 256.
*   `invoiceNo` (_string_) The invoice number.  
    Maximum length: 256. Example: `00000410`.
*   `lastModified` (_string (date-time)_) The timestamp when the order was last modified.  
    Example: `2020-11-04T14:13:31.061Z`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the order, not including price adjustments or service charges such as shipping.  
    Example: `4.95`.
*   `orderNo` (_OrderNo_, required)
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments.
*   `orderTotal` (_number (double)_) The total price, including products, shipping and, tax.  
    Example: `110.24`.
*   `paymentInstruments` (_array of PaymentInstrument_) The payment instruments list.
*   `paymentStatus` (_OrderPaymentStatus_)
*   `placeDate` (_string (date-time)_) The timestamp when the order was placed.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `productItems` (_array of ProductItem_) The product items.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `99`.
*   `remoteHost` (_string_) The IP of the host that placed this order. You can turn IP logging on or off for your site.  
    Maximum length: 40. Example: `127.0.0.1`.
*   `shipments` (_array of Shipment_) The shipments.
*   `shippingItems` (_array of ShippingItem_) The shipping items.
*   `shippingStatus` (_OrderShippingStatus_)
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments.  
    Example: `0.3`.
*   `siteId` (_SiteId_)
*   `sourceCode` (_string_) The source code assigned to the basket from which this order was created.  
    Maximum length: 256.
*   `sourceCodeGroupId` (_string_) The group ID of the source code assigned to the basket from which this order was created.  
    Minimum length: 1. Maximum length: 256.
*   `status` (_OrderStatus_)
*   `taxTotal` (_number (double)_) The total tax amount.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net).  
    Allowed values: `gross`, `net`. Example: `net`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderUpdateRequest

Request body to create an order and set custom attributes on the order. Please note that the custom attribute definition have to be configured both on the Basket and Order object in the platform.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderConfirmationStatusUpdateRequest

Request body to update the order confirmation status.

*   `status` (_OrderConfirmationStatus_, required)

### OrderExportStatusUpdateRequest

Request body to update the order export status.

*   `status` (_OrderExportStatus_, required)

### OrderExternalStatusUpdateRequest

Request body to update the order external status.

*   `status` (_string_, required) The new external status.  
    Minimum length: 1. Maximum length: 256. Example: `in_delivery`.

### OrderPaymentStatusUpdateRequest

Request body to update the order payment status.

*   `status` (_OrderPaymentStatus_, required)

### OrderShippingStatusUpdateRequest

Request body to update the order shipping status.

*   `status` (_OrderShippingStatus_, required)

### OmsStatusEventRequest

A single OMS-originated status event for an order. Exactly one of fulfillmentEvent or adjustment must be present.

One of: `any`, `any`.

*   `omsOrderId` (_string_) Optional external OMS identifier. Echoed back in forwarded order event payloads.  
    Minimum length: 1. Maximum length: 256. Example: `MAN-9988`.
*   `fulfillmentEvent` (_OmsFulfillmentEvent_)
*   `adjustment` (_OmsAdjustment_)

### OrderStatusUpdateRequest

Request body to update the order status.

*   `status` (_string_, required) The new status.  
    Allowed values: `created`, `new`, `completed`, `cancelled`, `failed`, `failed_with_reopen`. Example: `new`.

### PaymentInstrumentUpdateRequest

Request body to update custom properties.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentTransactionUpdateRequest

Request body to update custom properties.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingAddressUpdateRequest

Request body to update the shipping address.

Includes all fields of `Address`.

### Address

Document representing an order address.

*   `address1` (_string_) The first address line.  
    Maximum length: 256. Example: `45 Main Rd.`.
*   `address2` (_string_) The second address line.  
    Maximum length: 256. Example: `Apartment 204`.
*   `city` (_string_) The city.  
    Maximum length: 256. Example: `Burlington`.
*   `companyName` (_string_) The company name.  
    Maximum length: 256. Example: `Salesforce`.
*   `countryCode` (_CountryCode_)
*   `firstName` (_string_) The first name.  
    Maximum length: 256. Example: `Max`.
*   `fullName` (_string_) The full name.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `jobTitle` (_string_) The job title.  
    Maximum length: 256. Example: `Software Engineer`.
*   `lastName` (_string_) The last name.  
    Maximum length: 256. Example: `Mustermann`.
*   `phone` (_string_) The phone number.  
    Maximum length: 256. Example: `6175555555`.
*   `postBox` (_string_) The post office box.  
    Maximum length: 256. Example: `PO BOX 109`.
*   `postalCode` (_string_) The postal code.  
    Maximum length: 256. Example: `05408`.
*   `salutation` (_string_) The salutation.  
    Maximum length: 256. Example: `Mr`.
*   `secondName` (_string_) The second name.  
    Maximum length: 256.
*   `stateCode` (_string_) The state code.  
    Maximum length: 256. Example: `MA`.
*   `suffix` (_string_) The suffix.  
    Maximum length: 256. Example: `Sr`.
*   `suite` (_string_) The suite.  
    Maximum length: 256.
*   `title` (_string_) The title.  
    Maximum length: 256. Example: `Dr`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### CreateOrderPriceAdjustment

The Price Adjustment without Promotion and Coupon references - handled as `AdHocPriceAdjustments` internally.

The following fields are set:

*   manual = true
*   custom = true
*   promotionId = AD\_HOC\_PRICE\_ADJUSTMENT

*   `amount` (_number (double)_) Amount to deduct from the applied line item's price. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `6`.
*   `basePrice` (_number (double)_) The adjustment amount. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `-6`.
*   `grossPrice` (_number (double)_, required) The adjustment amount, including tax.  
    Example: `-6`.
*   `itemText` (_string_) The text describing the price adjustment.  
    Example: `6 Dollar off.`.
*   `netPrice` (_number (double)_, required) The adjustment amount, not including tax.  
    Example: `-5`.
*   `reasonCode` (_string_) The reason code why this price adjustment was made.  
    Example: `Special Offer.`.
*   `tax` (_number (double)_, required) The tax on the adjustment amount.  
    Example: `1`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this adjustment.  
    Example: `-5`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderPaymentInstrument

Document representing a payment instrument.

*   `paymentMethodId` (_string_, required) The payment method ID.  
    Maximum length: 256. Example: `PAYPAL`.
*   `paymentTransaction` (_object_) The payment transaction.
    
    Includes all fields of `CreateOrderPaymentTransaction`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderProductItems

Document representing a product item for an order.

*   `basePrice` (_number (double)_, required) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `34.32`.
*   `brand` (_string_) The brand of the line item.  
    Maximum length: 256. Example: `brand0001`.
*   `grossPrice` (_number (double)_, required) The gross price of the line item before applying any adjustments.  
    Example: `34.32`.
*   `itemText` (_string_) The text describing the item.  
    Example: `Green Umbrella`.
*   `netPrice` (_number (double)_, required) The net price of the line item before applying any adjustments.  
    Example: `30.32`.
*   `optionItems` (_array of CreateOrderOptionItem_) The array of option items. This array can be empty.  
    Maximum items: 10.
*   `priceAdjustments` (_array of CreateOrderPriceAdjustment_) The price adjustments on product line item.  
    Maximum items: 20.
*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product.  
    Maximum length: 256. Example: `green umbrella`.
*   `quantity` (_number (double)_, required) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `3`.
*   `shipmentId` (_string_, required) The ID of the shipment to which this item belongs. Shipment 'me' is reserved for the system and is not valid to pass.  
    Minimum length: 1. Maximum length: 256. Example: `shipment00001`.
*   `tax` (_number (double)_, required) The tax on the line item before applying any adjustments.  
    Example: `4`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `30.32`.
*   `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax). When omitted, only the aggregated tax/taxRate values are persisted.  
    Maximum items: 10.
*   `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. Just for display. No calculation or sanity checks are applied.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderShipment

Document representing a shipment for an order.

*   `shipmentId` (_string_, required) The order-specific ID of the shipment. The field shipmentId from line items refers to this value. The first shipment always become the standard shipment and is named 'me'. The ID 'me' is reserved for the standard shipment and it is not allowed to be used by the API caller.  
    Minimum length: 1. Maximum length: 256. Example: `shipment00001`.
*   `shippingMethod` (_string_, required) The shipping method. This has no reference to any shipments configured in the platform.  
    Example: `EXPRESS`.
*   `shippingAddress` (_object_, required) The shipping address.
    
    Includes all fields of `Address`.
    
*   `shippingTotal` (_number (double)_, required) The total price of all shipping charges in the shipment. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `4.95`.
*   `taxTotal` (_number (double)_, required) The total tax on the shipment.  
    Example: `0.75`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### BonusDiscountLineItem

Document representing a bonus discount line item.

*   `bonusProducts` (_array of ProductReference_) The bonus products from which the customer can choose.
*   `couponCode` (_string_) The coupon code that triggered the promotion, if applicable.  
    Maximum length: 256. Example: `5ties`.
*   `id` (_string_) The ID of the line item.  
    Minimum length: 1. Maximum length: 256. Example: `91f4dd8bfa0653d58b7783b04f`.
*   `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item.  
    Maximum length: 256. Example: `Buy1Get2`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderConfirmationStatus

The order confirmation status.

Type: `string`.

Allowed values: `confirmed`, `not_confirmed`. Example: `confirmed`.

### CouponItem

Document representing a coupon item.

*   `code` (_string_) The coupon code.  
    Maximum length: 256. Example: `5ties`.
*   `couponItemId` (_string_) The coupon item ID.  
    Minimum length: 1. Maximum length: 256. Example: `d4c9c0141e9c74c150225580f3`.
*   `statusCode` (_string_) The status of the coupon item.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion".  
    Example: `true`.

### CustomerInfo

Document representing a guest or logged-in customer.

*   `customerId` (_string_) The customer ID.  
    Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`.
*   `customerName` (_string_) The customer name.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `customerNo` (_string_) The customer number.  
    Maximum length: 100. Example: `0002352`.
*   `email` (_string_) The customer email address.  
    Maximum length: 256. Example: `no-reply@salesforce.com`.
*   `guest` (_boolean_) A flag indicating if the order was placed by a guest.  
    Example: `false`.

### GiftCertificateItem

A gift certificate item.

*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `50`.
*   `grossPrice` (_number (double)_) The gross price of the line item before applying any adjustments.  
    Example: `50`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Nintendo eShop gift card.`.
*   `netPrice` (_number (double)_) The net price of the line item before applying any adjustments.  
    Example: `50`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments.  
    Example: `0`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `50`.
*   `giftCertificateMerchantId` (_string_) The ID used to identify the certificate merchant.  
    Minimum length: 1. Maximum length: 256. Example: `Nintendo`.
*   `giftCertificateItemId` (_string_) The item ID.  
    Minimum length: 1. Maximum length: 256. Example: `629dea6e7b61e58da629b57b21`.
*   `message` (_string_) The gift certificate message.  
    Maximum length: 4000. Example: `Birthday present.`.
*   `recipientEmail` (_string_) The recipient email.  
    Maximum length: 256. Example: `no-reply@salesforce.com`.
*   `recipientName` (_string_) The recipient name.  
    Maximum length: 256. Example: `Daniel Mustermann`.
*   `senderName` (_string_) The sender name.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `shipmentId` (_string_) The ID of the shipment to which this item belongs.  
    Minimum length: 1. Maximum length: 256. Example: `me`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceAdjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level.

*   `basePrice` (_number (double)_) The adjustment amount. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `12`.
*   `grossPrice` (_number (double)_) The adjustment amount, including tax.  
    Example: `50`.
*   `itemText` (_string_) The text describing the adjustment.  
    Maximum length: 256. Example: `Employee discount applied.`.
*   `netPrice` (_number (double)_) The adjustment amount, not including tax.  
    Example: `38`.
*   `tax` (_number (double)_) The tax on the adjustment amount.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this adjustment.  
    Example: `50`.
*   `abTestSegment` (_object_) The AB testing segment, if enabled for the site and applicable to this price adjustment.
    
    Includes all fields of `ABTestSegment`.
    
*   `appliedDiscount` (_object_) Details describing the discount on which this price adjustment is based. For adjustments not based on a discount, this value is null.
    
    Includes all fields of `Discount`.
    
*   `campaignId` (_string_) The campaign ID of the promotion on which this price adjustment is based. For adjustments not based on a promotion, this value is null. For adjustments based on an AB test promotion, this value is not null, but isn't meaningful.  
    Minimum length: 1. Maximum length: 256. Example: `FreeShipping24`.
*   `couponCode` (_string_) The coupon code of the coupon on which this price adjustment is based. For adjustments not based on a coupon, this value is null.  
    Minimum length: 1. Maximum length: 256. Example: `5ties`.
*   `createdBy` (_string_) The user who created the price adjustment.  
    Maximum length: 256. Example: `Customer`.
*   `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created.  
    Example: `2021-02-25T09:58:04.691Z`.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.  
    Example: `false`.
*   `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false.  
    Example: `false`.
*   `priceAdjustmentId` (_string_) The price adjustment ID.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3eee797f062161f8b`.
*   `promotionId` (_string_, required) The promotion ID of the promotion on which this price adjustment is based. Custom price adjustment can assign an arbitrary promotion ID, but it must not be used by the promotion engine. If no promotion ID is specified, then the system assigns a generated ID.  
    Minimum length: 1. Maximum length: 256. Example: `FreeShipping24`.
*   `reasonCode` (_string_) The reason code why this price adjustment was made.  
    Minimum length: 1. Maximum length: 256. Example: `Employee discount was applied.`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentInstrument

Document representing an order payment instrument.

*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `6784532`.
*   `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked.  
    Maximum length: 256. Example: `******Gzzy`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `paymentInstrumentId` (_string_) The payment instrument ID.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3eee797f062162f8b`.
*   `paymentMethodId` (_string_) The payment method ID.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentTransaction` (_object_) The payment transaction.
    
    Includes all fields of `PaymentTransaction`.
    
*   `paymentDetails` (_object_) The normalized payment details for the order payment instrument. It is read only. Omitted when no details are available for the payment.
    
    Includes all fields of `PaymentDetails`.
    
*   `fraudDecisions` (_object_) The normalized fraud decisions for the order payment instrument. It is read only. Omitted when no decisions are returned.
    
    Includes all fields of `FraudDecisions`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductItem

Document representing a product item.

*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `99.99`.
*   `grossPrice` (_number (double)_) The gross price of the line item before applying any adjustments.  
    Example: `99.99`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Nintendo DS Game Console`.
*   `netPrice` (_number (double)_) The net price of the line item before applying any adjustments.  
    Example: `80.99`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments.  
    Example: `19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `99.99`.
*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments.  
    Example: `19`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item to which this bonus product relates.  
    Minimum length: 1. Maximum length: 256. Example: `ba248414e3eee797f062162f8b`.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether this item is a bonus product.  
    Example: `false`.
*   `brand` (_string_)  
    Maximum length: 256. Example: `Nintendo`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `externalLineItemStatus` (_string_) The external line item status.  
    Maximum length: 256. Example: `Available`.
*   `externalLineItemText` (_string_) The external line item text.  
    Example: `The item is available`.
*   `gift` (_boolean_) Returns true if the item is a gift.  
    Example: `false`.
*   `giftMessage` (_string_) The gift message.  
    Maximum length: 4000. Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_string_) The product item ID. Use this to identify this item when updating its quantity or creating a custom price adjustment for it.  
    Minimum length: 1. Maximum length: 256. Example: `430ef5aad3a24de59378458434`.
*   `minOrderQuantity` (_number (double)_) The minimum order quantity for this product.  
    Example: `1`.
*   `optionItems` (_array of OptionItem_) The option items.
*   `position` (_number (double)_) The position of the product line item.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.
*   `productId` (_ProductId_, required)
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Maximum length: 4000. Example: `Nintendo DS Game Console`.
*   `quantity` (_number (double)_) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_, required) The ID of the shipment to which this item belongs.  
    Minimum length: 1. Maximum length: 256. Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is the shipping item ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method.  
    Minimum length: 1. Maximum length: 256. Example: `006490dcc338feeafc71c964bf`.
*   `stepQuantity` (_number (double)_)  
    Example: `1`.
*   `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax).  
    Maximum items: 10.
*   `taxRate` (_number (double)_, required) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1.  
    Example: `0.19`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Shipment

Document representing a shipment.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments.  
    Example: `1.5`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments.  
    Example: `0.3`.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Maximum length: 4000. Example: `Happy Birthday`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping.  
    Example: `1.5`.
*   `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `29.99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `29.99`.
*   `shipmentId` (_string_, required) The order-specific ID of the shipment. The default value is 'me'.  
    Minimum length: 1. Maximum length: 256.
*   `shipmentNo` (_string_, required) The shipment number of this shipment. This number is automatically generated.  
    Maximum length: 256.
*   `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax.  
    Example: `39.99`.
*   `shippingAddress` (_object_) The shipping address.
    
    Includes all fields of `Address`.
    
*   `shippingMethod` (_object_) The shipping method.
    
    Includes all fields of `ShippingMethodReference`.
    
*   `shippingStatus` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments.  
    Example: `0.3`.
*   `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. This field value must match the summed up taxTotal, and an InvalidTaxTotalException is thrown if the values do not match.  
    Example: `1.8`.
*   `trackingNumber` (_string_) The tracking number of the shipment.  
    Maximum length: 256. Example: `1Z204E380338943508`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingItem

Document representing a shipping item.

*   `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `5.99`.
*   `grossPrice` (_number (double)_) The gross price of the shipping item before applying any adjustments.  
    Example: `5.99`.
*   `itemText` (_string_) The text describing the shipping item.  
    Maximum length: 256. Example: `Shipping`.
*   `netPrice` (_number (double)_) The net price of the shipping item before applying any adjustments.  
    Example: `5.99`.
*   `tax` (_number (double)_) The tax for the shipping item, not including price adjustments.  
    Example: `0.3`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this shipping item.  
    Example: `5.99`.
*   `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments.  
    Example: `0`.
*   `itemId` (_string_) The shipping item ID. Use this value to identify this shipping item when updating its quantity or creating a custom price adjustment for it.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3eee798f062162f8b`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `4.99`.
*   `shipmentId` (_string_) The ID of the shipment to which this item belongs.  
    Minimum length: 1. Maximum length: 256. Example: `me`.
*   `taxRate` (_number (double)_, required) The tax rate applicable to this shipping line item. For a 10% tax rate, the value is 0.1.  
    Example: `0.19`.
*   `type` (_string_) The type of shipping charge applicable to this shipping item.  
    Allowed values: `fixed_price`, `surcharge`. Default: `fixed_price`. Example: `fixed_price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderStatus

The order status.

Type: `string`.

Allowed values: `created`, `new`, `completed`, `cancelled`, `failed`. Example: `completed`.

### OmsFulfillmentEvent

A fulfillment event reported by an external OMS (for example, shipped, delivered, canceled).

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `ship-001`.
*   `occurredAt` (_string (date-time)_, required) RFC 3339 timestamp when the event occurred.  
    Example: `2026-06-03T10:15:00.000Z`.
*   `type` (_string_, required) Fulfillment event type. Common values: processing, shipped, in\_transit, delivered, failed\_attempt, canceled, undeliverable, returned\_to\_sender. Additional values are permitted.  
    Minimum length: 1. Maximum length: 256. Example: `shipped`.
*   `lineItems` (_array of OmsLineItemReference_, required)  
    Minimum items: 1. Maximum items: 200.
*   `trackingNumber` (_string_) Required when type is not "processing". Otherwise, a 400 Bad Request is returned.  
    Minimum length: 1. Maximum length: 256. Example: `1Z999AA10123456784`.
*   `trackingUrl` (_string (uri)_) Required when type is not "processing". Otherwise, a 400 Bad Request is returned.  
    Minimum length: 1. Maximum length: 2048. Example: `https://www.ups.com/track?tracknum=1Z999AA10123456784`.
*   `carrier` (_string_) The carrier handling the shipment (for example, UPS, FedEx, DHL).  
    Minimum length: 1. Maximum length: 256. Example: `UPS`.
*   `description` (_string_) Free-form note about the event provided by the OMS. Shown to support agents and forwarded to order event subscribers.  
    Minimum length: 1. Maximum length: 256. Example: `Handed to carrier`.

### OmsAdjustment

A post-order adjustment reported by an external OMS (for example, refund, return, cancellation).

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `ret-7788`.
*   `type` (_string_, required) Adjustment type (open string, for example, refund, return, credit, cancellation).  
    Minimum length: 1. Maximum length: 256. Example: `return`.
*   `occurredAt` (_string (date-time)_, required)  
    Example: `2026-06-03T10:15:00.000Z`.
*   `status` (_string_, required)  
    Allowed values: `pending`, `completed`, `failed`. Example: `completed`.
*   `lineItems` (_array of OmsAdjustmentLineItem_)  
    Maximum items: 200.
*   `totals` (_array of OmsAdjustmentTotal_)  
    Maximum items: 200.
*   `description` (_string_) Free-form note about the adjustment provided by the OMS. Shown to support agents and forwarded to order event subscribers.  
    Minimum length: 1. Maximum length: 256. Example: `Customer requested — defective item`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### CreateOrderPaymentTransaction

Document representing an order payment transaction.

*   `amount` (_number (double)_, required) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction.
    
    Includes all fields of `Status`.
    
*   `transactionId` (_string_, required) The payment service specific transaction ID.  
    Maximum length: 256. Example: `3226f0a3bc4b4f244d70dd1c2b`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderOptionItem

An option item represents an optional purchase related to a product item, and is always associated with that parent product item. For example, a refrigerator item can have a set of option items representing different warranties on the refrigerator. A shopper can only purchase one of the warranty option items together with the parent refrigerator item.

*   `basePrice` (_number (double)_, required) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `49.99`.
*   `grossPrice` (_number (double)_, required) The gross price of the line item before applying any adjustments.  
    Example: `99.99`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Extended Warranty - None`.
*   `netPrice` (_number (double)_, required) The net price of the line item before applying any adjustments.  
    Example: `49.99`.
*   `tax` (_number (double)_, required) The tax on the line item before applying any adjustments.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `50`.
*   `optionId` (_string_, required) The ID of the option.  
    Minimum length: 1. Maximum length: 256. Example: `consoleWarranty`.
*   `optionValueId` (_string_, required) The ID of the option value.  
    Minimum length: 1. Maximum length: 256. Example: `000`.
*   `priceAdjustments` (_array of CreateOrderPriceAdjustment_) The price adjustments.  
    Maximum items: 20.
*   `productId` (_ProductId_, required)

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### TaxItem

A specific tax item for a line item (e.g. state tax, county tax).

*   `id` (_string_, required) The tax item identifier (e.g. STATE, COUNTY).  
    Minimum length: 1. Maximum length: 256. Example: `STATE`.
*   `rate` (_number (double)_, required) The tax rate for this tax item. For a 7% tax rate, the value is 0.07.  
    Example: `0.07`.
*   `value` (_number (double)_) The tax value (amount) for this tax item.  
    Example: `13.99`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductReference

Document representing a product.

*   `productId` (_ProductId_)
*   `productName` (_string_) The name of the product.  
    Maximum length: 4000. Example: `Nintendo DS Game Console`.

### ABTestSegment

Document representing an AB test segment. In an AB test that compares different customer experiences, a segment defines the customers who receive a particular experience.

*   `testId` (_string_, required) The ID of the associated AB test.  
    Minimum length: 1. Maximum length: 40.
*   `segmentId` (_string_, required) The ID of the segment.  
    Minimum length: 1. Maximum length: 40.

### Discount

Document representing a discount.

*   `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts.  
    Example: `5`.
*   `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts.  
    Example: `0.19`.
*   `priceBookId` (_string_) The ID of the price book for discount types that use a price book.  
    Maximum length: 256. Example: `usd-sale-prices`.
*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`.

### PaymentCard

Document representing a payment card.

*   `cardType` (_string_) The payment card type (for example: Visa).  
    Maximum length: 256. Example: `Visa`.
*   `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired.  
    Example: `false`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.  
    Maximum length: 256. Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Minimum: 1. Maximum: 12. Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number. There may be a maximum of first 6 and last 4 digits.  
    Maximum length: 256. Example: `*********4422`.
*   `numberLastDigits` (_string_) The last digits of payment card number.  
    Maximum length: 4. Example: `4422`.
*   `validFromMonth` (_integer (int32)_) The month from which the payment card is valid.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year from which the payment card is valid.  
    Example: `2019`.

### PaymentTransaction

Document representing an order payment transaction.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction.
    
    Includes all fields of `Status`.
    
*   `transactionId` (_string_) The payment service specific transaction ID.  
    Maximum length: 256. Example: `3226f0a3bc4b4f244d70dd1c2b`.
*   `transactionDetails` (_object_) The normalized transaction details for the order payment transaction. It is read only. Omitted when no details are available.
    
    Includes all fields of `TransactionDetails`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentDetails

Normalized payment details for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no details are available for the payment. The values remain readable for historical orders.

*   `type` (_string_) The normalized payment method type. Expected values are `bancontact`, `card`, `gift_card`, `eps`, `ideal`, `klarna`, `sepa_debit`, `paypal`, `venmo`, `afterpay_clearpay`, `amazon_pay`, and `twint`. A custom value may also be returned. It is read only.  
    Maximum length: 256. Example: `card`.
*   `brand` (_string_) The normalized card brand. Expected values are `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, and `unknown`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `visa`.
*   `last4` (_string_) The last four digits of the payment instrument. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `walletType` (_string_) The normalized digital wallet used for the payment. Expected values are `apple_pay` and `google_pay`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `apple_pay`.
*   `expirationMonth` (_integer (int32)_) The month when the payment instrument expires. It is read only.  
    Minimum: 1. Maximum: 12. Example: `12`.
*   `expirationYear` (_integer (int32)_) The year when the payment instrument expires. It is read only.  
    Example: `2028`.
*   `token` (_string_) The reference token representing the payment instrument. This is an opaque identifier, not the card number (PAN). It is read only.  
    Maximum length: 40. Example: `pm_abc123`.
*   `tokenType` (_string_) The type of token backing the reference token. Expected values are `NETWORK` and `GATEWAY`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `GATEWAY`.
*   `accountHolderName` (_string_) The name of the payment instrument account holder. It is read only.  
    Maximum length: 256. Example: `Alex Shopper`.
*   `bin` (_string_) The bank identification number (BIN) of the payment card. It is read only.  
    Maximum length: 8. Example: `424242`.
*   `dpanLast4` (_string_) The last four digits of the device primary account number for a wallet-tokenized card. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `issuingCountry` (_string_) The ISO 3166-1 alpha-2 country code of the issuing bank. It is read only.  
    Maximum length: 2. Example: `US`.
*   `fundingType` (_string_) The normalized card funding type. Expected values are `CREDIT`, `DEBIT`, and `PREPAID`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `CREDIT`.

### FraudDecisions

Normalized fraud decisions for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no decisions are returned. The values remain readable for historical orders.

*   `preAuthorization` (_string_)
    
    The pre-authorization fraud decision used by the client to orchestrate checkout. Expected values are:
    
    *   `NOT_REVIEWED`: the payment instrument was not reviewed pre-authorization.
    *   `APPROVED`: the payment authorization can proceed.
    *   `CHALLENGE`: the payment authorization should be challenged with additional verification (for example, a 3D Secure challenge) before it can proceed.
    *   `DECLINED`: the payment authorization is declined.
    
    A custom value may also be returned. It is read only.
    
      
    Maximum length: 256. Example: `APPROVED`.
*   `postAuthorization` (_string_)
    
    The post-authorization fraud decision indicating whether the transaction is covered by a fraud guarantee. Expected values are:
    
    *   `NOT_REVIEWED`: the transaction was not reviewed for a fraud guarantee.
    *   `GUARANTEED`: the transaction is covered by a fraud guarantee.
    *   `NOT_GUARANTEED`: the transaction is not covered by a fraud guarantee.
    *   `PENDING`: the post-authorization fraud decision is still pending.
    
    A custom value may also be returned. It is read only.
    
      
    Maximum length: 256. Example: `GUARANTEED`.

### OptionItem

An option item represents an optional purchase related to a product item, and is always associated with the parent product item. For example, a refrigerator item can have a set of option items representing different warranties on the refrigerator. A shopper can only purchase one of the warranty option items together with the parent refrigerator item.

*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `49.99`.
*   `grossPrice` (_number (double)_) The gross price of the line item before applying any adjustments.  
    Example: `99.99`.
*   `gift` (_boolean_) Returns true if the item is a gift.  
    Example: `false`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Extended Warranty - None`.
*   `netPrice` (_number (double)_) The net price of the line item before applying any adjustments.  
    Example: `49.99`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `50`.
*   `optionId` (_string_) The ID of the option.  
    Minimum length: 1. Maximum length: 256. Example: `consoleWarranty`.
*   `optionValueId` (_string_) The ID of the option value.  
    Minimum length: 1. Maximum length: 256. Example: `000`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `productId` (_ProductId_, required)

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductListItemReference

Document representing product list item details.

*   `id` (_string_) The ID of the product list item.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3fee797f062162f8b`.
*   `priority` (_integer (int32)_) The priority of the product list item.
*   `product` (_object_) A reference to the associated product.
    
    Includes all fields of `ProductReference`.
    
*   `productList` (_object_) A reference to the associated product list.
    
    Includes all fields of `ProductListReference`.
    
*   `public` (_boolean_)  
    Example: `false`.
*   `purchasedQuantity` (_number (double)_, required) The total quantity of this item purchased from the product list.  
    Example: `0`.
*   `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item.  
    Minimum: 0. Example: `1`.
*   `type` (_string_) Specifies whether the item is a product or a gift certificate.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### ShippingMethodReference

Document representing a reference to a shipping method.

*   `id` (_string_) The shipping method ID.  
    Maximum length: 256. Example: `0000457`.

### OmsLineItemReference

A reference to an order line item affected by a fulfillment event, with the fulfilled quantity.

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `pli-001`.
*   `quantity` (_integer_, required) Fulfillment line-item quantity. Zero is allowed.  
    Minimum: 0. Example: `2`.

### OmsAdjustmentLineItem

A reference to an order line item affected by an adjustment, with a signed quantity (negative for reductions/returns).

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `pli-001`.
*   `quantity` (_integer_, required) Signed quantity; negative for reductions or returns.  
    Example: `-1`.

### OmsAdjustmentTotal

A signed monetary total for an adjustment, broken down by cost category, in minor currency units (for example, cents for EUR or USD; decimal places follow the order's currency).

*   `type` (_string_, required) Cost category. Well-known values: subtotal, items\_discount, discount, fulfillment, tax, fee, total. Additional values are permitted.  
    Minimum length: 1. Maximum length: 256. Example: `total`.
*   `amount` (_integer_, required) Signed amount in minor currency units (for example, cents for EUR or USD); the number of decimal places follows the order's currency. Negative for money returned to the buyer.  
    Example: `-1999`.
*   `displayText` (_string_) Text describing the adjustment total for display.  
    Minimum length: 1. Maximum length: 256. Example: `Refund`.

### Status

Document representing a status of an object.

*   `code` (_string_) The status code.  
    Maximum length: 256. Example: `OK`.
*   `message` (_string_) The message corresponding to the status.  
    Maximum length: 256. Example: `Credit Card successfully authorized.`.
*   `status` (_integer (int32)_) A constant corresponding to the status code. The value is 0 for OK, 1 for ERROR, and 2 for WARN.  
    Minimum: 0. Maximum: 2. Example: `0`.

### TransactionDetails

Normalized transaction details for the order payment transaction. Specific fields are populated depending on the `paymentDetails.type` value. All properties are optional and read only. The object is omitted entirely when no details are available.

*   `cvcResult` (_string_) The card verification code check result. Expected values are `MATCH`, `NO_MATCH`, `NOT_PROCESSED`, and `UNAVAILABLE`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `MATCH`.
*   `avsResult` (_string_) The address verification service result. Expected values are `Y` (full match), `N` (no match), `A` (address only), `Z` (postal code only), `U` (unavailable), `S` (unsupported), and `R` (retry). A custom value may also be returned. It is read only.  
    Maximum length: 1. Example: `Y`.
*   `threeDSResult` (_string_) The 3D Secure authentication result. Expected values are `AUTHENTICATED`, `ATTEMPTED`, `FAILED`, `REJECTED`, and `UNAVAILABLE`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `AUTHENTICATED`.
*   `threeDSVersion` (_string_) The 3D Secure protocol version. Expected values are `V1` and `V2`. A custom value may also be returned. It is read only.  
    Maximum length: 2. Example: `V2`.
*   `threeDSTransactionId` (_string_) The 3D Secure transaction identifier. It is read only.  
    Maximum length: 40. Example: `f25084f0-5b16-4c0a-ae5d-b24e4f`.
*   `electronicCommerceIndicator` (_string_) The electronic commerce indicator (ECI) value returned by the processor. It is read only.  
    Maximum length: 3. Example: `05`.
*   `approvalCode` (_string_) The approval code returned by the provider on a successful gift card capture. It is read only.  
    Maximum length: 256. Example: `A1B2C3`.
*   `reasonCode` (_string_) The reason code returned by the provider on a failed gift card capture. Expected values are `DECLINED` and `INSUFFICIENT_FUNDS`. A custom value may also be returned. It is read only.  
    Maximum length: 256. Example: `INSUFFICIENT_FUNDS`.
*   `processorResponseText` (_string_) The human-readable gift card processor response text. The language and localization of this text are provider-defined and may vary by provider integration. It is read only.  
    Maximum length: 256. Example: `Insufficient funds`.

### ProductListReference

Document representing a product list.

*   `description` (_string_) The description of this product list.  
    Maximum length: 256.
*   `name` (_string_) The name of this product list.  
    Maximum length: 256.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers.  
    Example: `false`.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `wish_list`.