title: Carts
domain: store
routes:
  - method: GET
    path: /carts/:id
  - method: POST
    path: /carts
  - method: POST
    path: /carts/:id
  - method: POST
    path: /carts/:id/complete-cart
  - method: POST
    path: /carts/:id/line-items
  - method: POST
    path: /carts/:id/line-items/:line_id
  - method: POST
    path: /carts/:id/payment-sessions
  - method: POST
    path: /carts/:id/payment-session/update
  - method: POST
    path: /carts/:id/payment-sessions/:provider_id/refresh
  - method: POST
    path: /carts/:id/payment-session
  - method: POST
    path: /carts/:id/shipping-methods
  - method: DELETE
    path: /carts/:id/payment-sessions/:provider_id
  - method: DELETE
    path: /carts/:id/line-items/:line_id
  - method: DELETE
    path: /carts/:id/discounts/:code
route: /carts
description: >
  A Cart is the preliminary step to an Order. The Cart holds a collection of 
  items that the customer wishes to purchase, along with the customer's
  preferred payment and shipping method.
endpoints:
  - path: /
    method: POST
    title: Create a Cart
    body:
      - name: region_id
        type: String
        required: false
        description: Id of the region to associate the cart with.
      - name: items
        type: List
        required: false
        description: List of objects with `variant_id` and `quantity`.
    description: >
      Creates a Cart within the given region and with the initial items. If no
      `region_id` is provided the cart will be associated with the first Region
      available. If no items are provided the cart will be empty after creation.
      If a user is logged in the cart's customer id and email will be set.
  - path: /:id
    method: GET
    title: Retrieve a Cart
    description: >
      Retrieves an existing cart.
  - path: /:id
    method: POST
    title: Update a Cart
    body:
      - name: region_id
        type: String
        description: Id of a region.
      - name: email
        type: String
        description: >
          Customer's email where they will receive transactional emails etc.
      - name: billing_address
        type: Address
        description: >
          The billing address for the order.
      - name: shipping_address
        type: Address
        description: >
          The shipping address for the order. Will be sent to the fulfillment
          provider when the items are ready to be shipped.
      - name: discounts
        type: List
        description: >
          A list of objects with `code` that represents a discount code to be
          applied to the cart.
      - name: customer_id
        type: String
        description: >
          A list of objects with `code` that represents a discount code to be
          applied to the cart.
    description: >
      Updates an existing cart with the provided data. Updating the `region_id`
      will change the prices of the items in the cart to match the prices 
      defined for the region. You can apply multiple discounts at once by 
      calling the endpoint with an array of discounts.
  - path: /:id/complete-cart
    method: POST
    title: Complete cart
    description: >
      Completes a cart. The following steps will be performed. Payment authorization 
      is attempted and if more work is required, we simply return the cart for further updates.
      If payment is authorized and order is not yet created, we make sure to do so. 
      The completion of a cart can be performed idempotently with a provided header `Idempotency-Key`.
      If not provided, we will generate one for the request.
  - path: /:id/line-items
    method: POST
    title: Add line item
    body:
      - name: variant_id
        type: String
        required: true
        description: The id of the variant that should be added to the cart.
      - name: quantity
        type: Integer
        required: true
        description: >
          The quantity of the variant to add to the cart. Must be
          greater than 0.
      - name: metadata
        type: Object
        description: >
          Optional metadata that may be needed for display purposes or other 
          functionality.
  - path: /:id/line-items/:line_id
    method: POST
    title: Update line item
    body:
      - name: quantity
        type: Integer
        description: The desired quantity of the line item.
    description: >
      Updates the quantity of a line item. If the variant associated with the 
      line item is stock managed, the endpoint will respond with an error when
      the inventory level cannot fulfill the desired quantity.
  - path: /:id/line-items/:line_id
    method: DELETE
    title: Remove line item
    description: >
      Removes a the given line item from the cart.
  - path: /:id/discounts/:code
    method: DELETE
    title: Remove discount code
    description: Removes a discount code from the cart.
  - path: /:id/payment-sessions
    method: POST
    title: Create payment sessions
    description: >
      Initializes the payment sessions that can be used to pay for the items of
      the cart. This is usually called when a customer proceeds to checkout.
  - path: /:id/payment-sessions/:provider_id
    method: DELETE
    title: Delete payment session
    description: >
      Deletes a payment session. Note that this will initialize a new payment
      session with the provider. This is usually used if the payment session
      reaches a state that cannot be recovered from.
  - path: /:id/payment-session
    method: POST
    title: Set payment session on cart
    params:
      - name: provider_id
        type: String
        required: true
        description: Id of the provider (e.g. stripe).
    description: >
      Adds or updates the payment method that will be used to pay for the items
      in the cart. The payment is not processed until the payment provider's 
      authorization functionality is called. You should consult with your 
      installed payment plugins to find information about how to authorize a 
      payment.
  - path: /:id/payment-session/update
    method: POST
    title: Update payment session on cart
    params:
      - name: session
        type: Dictionary
        required: true
        description: >
          The session object needs to have a `provider_id` (e.g. stripe) and `data`, that holds the update data for the session. 
          The data object can be anything that might be needed for the payment provider to process the
          payment. The requirements of `data` will be different across payment 
          methods, and you should look at your installed payment providers to
          find out what to send..
    description: >
      Updates the payment session that will be used to pay for the items
      in the cart. The payment is not processed until the payment provider's 
      authorization functionality is called. You should consult with your 
      installed payment plugins to find information about how to authorize a 
      payment.
  - path: /:id/shipping-methods
    method: POST
    title: Add shipping method
    body:
      - name: option_id
        type: String
        required: true
        description: The id of the shipping option to use.
      - name: data
        type: Dictionary
        description: >
          Used to hold any data that the shipping method may need to process the 
          fulfillment of the order. Look at the documentation for your installed
          fulfillment providers to find out what to send.
    description: >
      Adds a shipping method to the cart.
response: |
  {
    "cart": {
      "id": "cart_1234",
      "email": null,
      "billing_address_id": null,
      "billing_address": null,
      "shipping_address_id": "addr_1234",
      "shipping_address": {
        "id": "addr_1234",
        "customer_id": null,
        "company": null,
        "first_name": null,
        "last_name": null,
        "address_1": null,
        "address_2": null,
        "city": null,
        "country_code": "dk",
        "province": null,
        "postal_code": null,
        "phone": null,
        "created_at": "2021-02-04T15:40:54.691Z",
        "updated_at": "2021-02-04T15:40:54.691Z",
        "deleted_at": null,
        "metadata": null
      },
      "items": [{
        "id": "item_1234",
        "cart_id": "cart_1234",
        "order_id": null,
        "swap_id": null,
        "claim_order_id": null,
        "title": "Terry Towel",
        "description": "30x30",
        "thumbnail": "",
        "is_giftcard": false,
        "should_merge": true,
        "allow_discounts": true,
        "has_shipping": false,
        "unit_price": 6000,
        "variant_id": "variant_1234",
        "variant": {
          "id": "variant_1234",
          "title": "30x30",
          "product_id": "prod_1234",
          "sku": null,
          "barcode": null,
          "ean": null,
          "upc": null,
          "inventory_quantity": 9999,
          "allow_backorder": false,
          "manage_inventory": true,
          "hs_code": null,
          "origin_country": null,
          "mid_code": null,
          "material": null,
          "weight": null,
          "length": null,
          "height": null,
          "width": null,
          "created_at": "2021-01-19T17:09:01.864Z",
          "updated_at": "2021-02-02T02:43:17.718Z",
          "deleted_at": null,
            "metadata": null
        },
        "quantity": 1,
        "fulfilled_quantity": null,
        "returned_quantity": null,
        "shipped_quantity": null,
        "created_at": "2021-02-04T15:42:12.514Z",
        "updated_at": "2021-02-04T15:42:12.514Z",
        "metadata": {}
      }],
      "region_id": "reg_1234",
      "region": {
        "id": "reg_1234",
        "name": "Denmark",
        "currency_code": "dkk",
        "tax_rate": "25",
        "tax_code": null,
        "countries": [{
          "id": 60,
          "iso_2": "dk",
          "iso_3": "dnk",
          "num_code": 208,
          "name": "DENMARK",
          "display_name": "Denmark",
          "region_id": "reg_1234"
        }],
        "payment_providers": [{
          "id": "stripe",
          "is_installed": true
        }],
        "fulfillment_providers": [{
          "id": "manual",
          "is_installed": true
        }],
        "created_at": "2021-01-19T17:09:01.864Z",
        "updated_at": "2021-01-21T15:44:05.492Z",
        "deleted_at": null,
        "metadata": null
      },
      "discounts": [],
      "gift_cards": [],
      "customer_id": null,
      "payment_sessions": [{
        "id": "ps_1234",
        "cart_id": "cart_1234",
        "provider_id": "stripe",
        "is_selected": true,
        "status": "pending",
        "data": {},
        "created_at": "2021-02-08T11:37:17.906Z",
        "updated_at": "2021-02-08T11:37:17.906Z",
        "idempotency_key": null
      }],
      "payment_id": null,
      "payment": null,
      "shipping_methods": [],
      "type": "default",
      "completed_at": null,
      "created_at": "2021-02-04T15:40:54.691Z",
      "updated_at": "2021-02-04T15:40:54.691Z",
      "deleted_at": null,
      "metadata": null,
      "idempotency_key": null,
      "payment_session": {
        "id": "ps_1234",
        "cart_id": "cart_1234",
        "provider_id": "stripe",
        "is_selected": true,
        "status": "pending",
        "data": {},
        "created_at": "2021-02-08T11:37:17.906Z",
        "updated_at": "2021-02-08T11:37:17.906Z",
        "idempotency_key": null
      },
      "shipping_total": 0,
      "discount_total": 0,
      "tax_total": 1500,
      "gift_card_total": 0,
      "subtotal": 6000,
      "total": 7500
    }
  }