Placing orders

You can use the Shopping API and the Associate App API to create and manage carts in order to place orders in the NewStore platform and manage item exchanges.

See the External orders API docs for more information on importing external orders into the platform.

Important

Talk to your integrator or contact the support team before you start working with the API.

A cart goes through different states:

• draft: The cart has been created and can be modified but lacks the required information to be checked out.
• ready: The cart can be modified and has all the information needed to be checked out. The required information depends on the situation but it typically is: items, potential shipping information or potential payment information...
• placed: The cart has been placed and cannot be modified anymore. The payment and shipping information is being processed.
• accepted: The cart's life cycle is over, the payment operations have been successfully performed and an order has been created from the cart. You cannot set the state of the cart to this state.
• failed: The payment operations have failed. The cart's payment information must be fixed before being placed again. You cannot set the state of the cart to this state.

Placing an order

Creating a cart

To create a cart:

1. Call the Create cart method. The cart's state is draft.
2. Add items to the cart using the Update cart method.

Adding a shipping option

Add a shipping option if you are dealing with an endless-aisle order:

1. Request a shipping solution using the Get shipping method.
2. Add the shipping solution to the cart in the shipping_solution_id using the Update cart method.

Adding payments

Call the Update cart method to:

1. Add payment information to the cart in the payments property

   Important

   The sum of all the payment amounts should be equal to the order total.

2. Change the cart's state property to ready. The response will contain a different state if the cart cannot be set to ready in case of a payment amount issue or shipping address issue.

Placing the order

1. Place the order by changing the state property to placed using the Update cart method.

   The payment information and shipping information is processed by external parties.

2. Check the status of the payments by calling the Update cart method with an empty body.

If the processing of the cart data is successful, you can get the sales receipt by calling the Get document method.

Exchanging items

Use the Shopping API to exchange items. The exchange process consists of returning one or more items and adding one or more items in exchange for the items returned.

When you exchange an item for another one, the total price of the new cart changes depending on which items are involved in the exchange.

The exchange can be of the following types:

• Negative: the new total amount is less than the returned item(s) so a refund will happen.
• Positive: the new total amount is greater than the value of the returned item(s) so another payment must be added.
• Even: the new total is equal to the value of the returned item(s), so no payment must be added and no refund will happen.

In order to save the amount that has to be either payed or refunded during an exchange, a store credit is created in the response of the Update cart method that corresponds to the total value of the returns.

Initiating an exchange

To initiate an exchange, create a new cart and add return information using the returns property using the Update cart method.

"returns": [{
  "order_id": "f31b1c90-c4a6-4015-af2b-fe07dcfefb6f",
  "item_id": "b46b4343-2752-4c36-a057-12abae09c927",
  "return_reason": "Too Large",
  "return_code": 1
}]

The response contains 2 important elements:

• An unchangeable potential_store_credit property in the payment property.

  "payments": {
    "potential_store_credit": {
      "amount": 230.82,
      "metadata": null,
      "method": "store_credit",
      "processed_at": null,
      "processor": "store_credit",
      "type": "captured",
      "wallet": ""
    }
  }

  This payment reflects the potential refund amount to be considered during the exchange. This amount does not change when adding new products to the cart, since this is a fixed amount corresponding to the return. This property remains in the cart as long as the cart is in the draft or ready state.

• The amount in the exchange property:

  It always contains the amount refunded/charged or zero, depending on the type:

  • Negative: the amount is negative.
  • Positive: the amount is positive.
  • Even: the amount is zero.

  "exchange": {
    "amount": -100.68,
    "type": "negative"
  }

Processing an exchange

To process an exchange:

1. Create a new cart.
2. Check that the total of the payments matches the total of the cart.
3. Set the cart's state to placed.

Check the response of your request for the following changes:

• The potential_store_credit property is replaced by a payment listed in the payments property.

  This payment represents the amount which was actually issued as store credit.

• If the exchange is a negative exchange, a refund amount is added to the refund object in every return property.

• A return is initiated. The status of this is reflected in the return_status property.

  • If the return fails, the cart is back to the draft state.
  • If the return is successful, the checkout proceeds and all payments are processed, including the store credit payment.

note

For positive exchanges, non-store-credit payments can fail. When this happens, the store credit is automatically refunded and the exchange is aborted but the items are returned. In this case, the same exchange can not happen again as the item have already been returned.

Sequence diagrams

In-store purchase

sequenceDiagram participant Client participant ShoppingAPI participant PaymentProcessor Client->>ShoppingAPI: Create cart activate ShoppingAPI Note right of ShoppingAPI: The cart is created in 'draft' status ShoppingAPI-->>Client: 201 {id: <order-id>, ...} deactivate ShoppingAPI Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: The cart is updated with the payment data ShoppingAPI-->>Client: 200 {status: 'ready'} deactivate ShoppingAPI Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: The cart is updated with {status: 'placed'}. After that The cart processing is started by NewStore platform. ShoppingAPI-->>Client: 200 {status: 'placed'} deactivate ShoppingAPI activate ShoppingAPI ShoppingAPI-->>PaymentProcessor: add payments activate PaymentProcessor Note right of PaymentProcessor: Payment processing is initiated by the NewStore platform. Token payments are authorized, and all the payments are validated. The results are communicated asynchronously to the Shopping API. deactivate PaymentProcessor PaymentProcessor-->>ShoppingAPI: payment_1 succeeded/failed PaymentProcessor-->>ShoppingAPI: payment_2 succeeded/failed PaymentProcessor-->>ShoppingAPI: payment_3 succeeded/failed Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: Each payments has a corresponding entry in 'payment_statuses'. Once all the payments are processed, the cart status is updated to either 'accepted' or 'failed'. ShoppingAPI-->>Client: 200 {status: `accepted/failed`} deactivate ShoppingAPI Client->>ShoppingAPI: GET /orders/<order-id>/sales_receipt activate ShoppingAPI Note right of ShoppingAPI: Sales receipt is generated asynchronously after the order is accepted. ShoppingAPI-->>Client: 307: redirect to pdf file ShoppingAPI-->>Client: 404: not found deactivate ShoppingAPI

Endless aisle

sequenceDiagram participant Client participant ShoppingAPI participant PaymentProcessor Client->>ShoppingAPI: Create cart activate ShoppingAPI Note right of ShoppingAPI: The order is created in 'draft' status. ShoppingAPI-->>Client: 201 {id: <order-id>, ...} deactivate ShoppingAPI Client->>ShoppingAPI: Create cart/<order-id>/shipping_solutions activate ShoppingAPI Note right of ShoppingAPI: Shipping solutions are generated for the order. ShoppingAPI-->>Client: 200 [list of shipping solutions] deactivate ShoppingAPI Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: The order is updated with the 'shipping_solution_id' from the previous step. ShoppingAPI-->>Client: 200 {status: 'draft'} deactivate ShoppingAPI Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: The order is updated with the payment data. ShoppingAPI-->>Client: 200 {status: 'ready'} deactivate ShoppingAPI Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: The order is updated with {status: 'placed'}. After that the order processing is started by NewStore platform. ShoppingAPI-->>Client: 200 {status: 'placed'} deactivate ShoppingAPI activate ShoppingAPI ShoppingAPI-->>PaymentProcessor: add payments activate PaymentProcessor Note right of PaymentProcessor: Payment processing is initiated by the NewStore platform. Token payments are authorized, and all the payments are validated. The results are communicated asynchronously to the Shopping API. deactivate PaymentProcessor PaymentProcessor-->>ShoppingAPI: payment_1 succeeded/failed PaymentProcessor-->>ShoppingAPI: payment_2 succeeded/failed PaymentProcessor-->>ShoppingAPI: payment_3 succeeded/failed Client->>ShoppingAPI: Update cart activate ShoppingAPI Note right of ShoppingAPI: Each payments has a corresponding entry in 'payment_statuses'. Once all the payments are processed, the order status is updated to either 'accepted' or 'failed'. ShoppingAPI-->>Client: 200 {status: 'accepted/failed'} deactivate ShoppingAPI Client->>ShoppingAPI: GET /orders/<order-id>/sales_receipt activate ShoppingAPI Note right of ShoppingAPI: Sales receipt is generated asynchronously after the order is accepted and will be ready eventually. ShoppingAPI-->>Client: 307: redirect to pdf file ShoppingAPI-->>Client: 404: not found deactivate ShoppingAPI

Exchange

sequenceDiagram participant Cl as Client participant S as ShoppingAPI participant C as Cart participant B as Backend Cl->>S: Create cart activate S S->>C: Create new cart S->>Cl: 201 {id: <order_id>} deactivate S Cl->>S: Update cart {"returns":[], "items":[...]} activate S S->>C: Update activate C C->>B: Precalculate refund B->>C: Return result C->>C: Add potential_store_credit Note over C: State = Ready C->>S: Return result deactivate C S->>Cl: OK 200 {"status":"ready", "exchange": ...} deactivate S Cl->>S: Update cart {"status":"placed"} Activate S S->>C: return result activate C Note over C: State = Placed C->>B: Initiate return activate B B->>C: Response with return deactivate B C->>C: Add store credit payment C-->>B: Use store credit payment C-->>B: Use extra payments if needed C->>S: OK deactivate C S->>Cl: OK 200 with {"status":"placed"} deactivate S Cl->>C: Check status activate C C->>Cl: {"status":"placed"} deactivate C B-->>C: All payments were authorized activate C Note over C: Accepted C->>B: Create sales order in on_hold state deactivate C Cl->>C: Check for status activate C C->>Cl: {"status":"Accepted"} deactivate C

Related topics

• Getting started with NewStore APIs