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