Elastic Path Cart Shipping Groups API

openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Cart Shipping Groups API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Cart Shipping Groups
paths:
  /v2/carts/{cartID}/shipping-groups:
    get:
      tags:
      - Cart Shipping Groups
      summary: Retrieve all shipping groups for a cart
      operationId: getShippingGroups
      description: Retrieve all shipping groups for a cart
      parameters:
      - name: cartID
        in: path
        required: true
        description: The ID of the cart
        schema:
          type: string
      responses:
        '200':
          description: A list of shipping groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShippingGroupResponse'
              examples:
                Retrieve Shipping Groups for a Cart:
                  value:
                    data:
                    - id: 96b1d104-0d2e-41fd-9543-6c3c5a698959
                      type: shipping_group
                      relation: cart
                      cart_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959
                      shipping_type: standard
                      tracking_reference: TRACK123
                      meta:
                        shipping_display_price:
                          total:
                            amount: 1000
                            currency: USD
                            formatted: $10.00
                          base:
                            amount: 800
                            currency: USD
                            formatted: $8.00
                          tax:
                            amount: 200
                            currency: USD
                            formatted: $2.00
                          fees:
                            amount: 0
                            currency: USD
                            formatted: $0.00
                      address:
                        first_name: John
                        last_name: Doe
                        phone_number: (555) 555-1234
                        company_name: ACME Corp
                        line_1: 123 Main St
                        line_2: Suite 100
                        city: Portland
                        postcode: '97201'
                        county: Multnomah
                        country: US
                        region: Oregon
                        instructions: Leave at front door
                      delivery_estimate:
                        start: '2024-01-15T00:00:00Z'
                        end: '2024-01-20T00:00:00Z'
        '404':
          description: Cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
    post:
      tags:
      - Cart Shipping Groups
      summary: Create a new shipping group for a cart
      operationId: createShippingGroup
      description: Create a new shipping group for a cart
      parameters:
      - name: cartID
        in: path
        required: true
        description: The ID of the cart
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShippingGroupRequest'
      responses:
        '201':
          description: Shipping group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingGroupEntityResponse'
              example:
                data:
                  id: 96b1d104-0d2e-41fd-9543-6c3c5a698959
                  type: shipping_group
                  relation: cart
                  cart_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959
                  shipping_type: standard
                  tracking_reference: TRACK123
                  address:
                    first_name: John
                    last_name: Doe
                    phone_number: (555) 555-1234
                    company_name: ACME Corp
                    line_1: 123 Main St
                    line_2: Suite 100
                    city: Portland
                    postcode: '97201'
                    county: Multnomah
                    country: US
                    region: Oregon
                    instructions: Leave at front door
                  delivery_estimate:
                    start: '2024-01-15T00:00:00Z'
                    end: '2024-01-20T00:00:00Z'
                  created_at: '2024-01-10T12:00:00Z'
                  updated_at: '2024-01-10T12:00:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                currency_mismatch:
                  value:
                    errors:
                    - status: 400
                      title: Cart Currency Mismatch
                      detail: This cart uses USD, cannot add shipping group with currency EUR
                invalid_dates:
                  value:
                    errors:
                    - status: 400
                      title: Date Logic Discrepancy
                      detail: The start date cannot occur after the end date
        '404':
          description: Cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              example:
                errors:
                - status: 404
                  title: Not Found
                  detail: Cart not found
  /v2/carts/{cartId}/shipping-groups/{shippingGroupId}:
    get:
      tags:
      - Cart Shipping Groups
      summary: Retrieve a specific shipping group for a cart
      operationId: getShippingGroupById
      description: Retrieve a specific shipping group for a cart
      parameters:
      - name: cartId
        in: path
        required: true
        description: The ID of the cart
        schema:
          type: string
      - name: shippingGroupId
        in: path
        required: true
        description: The ID of the shipping group
        schema:
          type: string
      responses:
        '200':
          description: Shipping group details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ShippingGroupResponse'
              example:
                data:
                  id: 7cfa5b07-092e-4dbe-bbad-55a771a34117
                  type: shipping_group
                  relation: cart
                  cart_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959
                  shipping_type: standard
                  tracking_reference: TRACK123
                  address:
                    first_name: John
                    last_name: Doe
                    phone_number: (555) 555-1234
                    company_name: ACME Corp
                    line_1: 123 Main St
                    line_2: Suite 100
                    city: Portland
                    postcode: '97201'
                    county: Multnomah
                    country: US
                    region: Oregon
                    instructions: Leave at front door
                  delivery_estimate:
                    start: '2024-01-15T00:00:00Z'
                    end: '2024-01-20T00:00:00Z'
                  meta:
                    shipping_display_price:
                      total:
                        amount: 1000
                        currency: USD
                        formatted: $10.00
                      base:
                        amount: 800
                        currency: USD
                        formatted: $8.00
                      tax:
                        amount: 200
                        currency: USD
                        formatted: $2.00
                      fees:
                        amount: 0
                        currency: USD
                        formatted: $0.00
        '404':
          description: Shipping group or cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                cart_not_found:
                  value:
                    errors:
                    - status: 404
                      title: Not Found
                      detail: Cart not found
                shipping_group_not_found:
                  value:
                    errors:
                    - status: 404
                      title: Cart shipping group not found
                      detail: Cart shipping group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for cart [abc123]
    put:
      tags:
      - Cart Shipping Groups
      summary: Update a shipping group for a cart
      description: Update a specific shipping group for a cart
      operationId: updateShippingGroup
      parameters:
      - name: cartId
        in: path
        required: true
        description: The ID of the cart
        schema:
          type: string
      - name: shippingGroupId
        in: path
        required: true
        description: The ID of the shipping group
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCartShippingGroupRequest'
            example:
              data:
                type: shipping_group
                shipping_type: express
                tracking_reference: TRACK456
                shipping_price:
                  base: 1500
                  tax: 300
                  fees: 200
                address:
                  first_name: John
                  last_name: Doe
                  phone_number: (555) 555-1234
                  company_name: ACME Corp
                  line_1: 123 Main St
                  line_2: Suite 100
                  city: Portland
                  postcode: '97201'
                  county: Multnomah
                  country: US
                  region: Oregon
                  instructions: Leave at front door
      responses:
        '200':
          description: Shipping group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingGroupEntityResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                currency_mismatch:
                  value:
                    errors:
                    - status: 400
                      title: Cart Currency Mismatch
                      detail: The existing shipping group uses USD, cannot update shipping group with currency EUR
                invalid_dates:
                  value:
                    errors:
                    - status: 404
                      title: Date Logic Discrepancy
                      detail: The start date cannot occur after the end date
        '404':
          description: Shipping group or cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              example:
                errors:
                - status: 404
                  title: Cart shipping group not found
                  detail: Cart shipping group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for cart [abc123]
    delete:
      tags:
      - Cart Shipping Groups
      summary: Delete Cart Shipping Group
      description: 'Deletes a shipping group from a cart. You cannot delete a shipping group that is attached to cart items.

        You must first remove the shipping group from all cart items before deleting the shipping group.

        '
      operationId: deleteCartShippingGroup
      parameters:
      - name: cartId
        in: path
        required: true
        description: The ID of the cart
        schema:
          type: string
      - name: shippingGroupId
        in: path
        required: true
        description: The ID of the shipping group to delete
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted the shipping group
        '400':
          description: Cannot delete shipping group that is attached to cart items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              example:
                errors:
                - status: 400
                  title: Cannot delete shipping group
                  detail: Cannot delete shipping groups attached to cart items. Please remove the shipping group from its cart items and try again.
        '404':
          description: Cart or shipping group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
components:
  schemas:
    Money:
      type: object
      properties:
        amount:
          type: integer
          description: Amount in minor currency units (e.g., cents).
        currency:
          type: string
          description: ISO 4217 currency code (e.g., "USD").
        includes_tax:
          type: boolean
          description: Whether the amount includes tax.
      required:
      - amount
      - currency
      - includes_tax
    OrderPriceWrapperMeta:
      description: Order pricing information.
      type: object
      properties:
        with_tax:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        without_tax:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        tax:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        discount:
          $ref: '#/components/schemas/DiscountFormattedPriceData'
        balance_owing:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        paid:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        authorized:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        without_discount:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        shipping:
          $ref: '#/components/schemas/NonNegativeFormattedPriceData'
        shipping_discount:
          $ref: '#/components/schemas/DiscountFormattedPriceData'
      required:
      - with_tax
      - without_tax
      - tax
      - discount
      - balance_owing
      - paid
      - authorized
      - without_discount
      - shipping
      - shipping_discount
    OrderItemResponse:
      title: OrderItemResponse
      type: object
      properties:
        type:
          description: The type represents the object being returned.
          type: string
          examples:
          - order_item
        id:
          description: The unique identifier for this order item.
          type: string
          format: uuid
          readOnly: true
          examples:
          - 68bf8510-bebf-47b1-96ba-8a9930c7d928
        quantity:
          description: The quantity of this item were ordered.
          type: number
          examples:
          - 1
        product_id:
          description: The unique identifier for this order item.
          type: string
          format: uuid
          readOnly: true
          examples:
          - 4e9c6098-9701-4839-a69c-54d8256d9012
        subscription_offering_id:
          description: The unique identifier for the subscription offering for this order item.
          type: string
          format: uuid
          readOnly: true
          examples:
          - 69a39623-e681-415e-83c0-e1281010c77d
        name:
          description: The name of this order item.
          type: string
          examples:
          - Product 123
        sku:
          description: The SKU code for the order item.
          type: string
          examples:
          - IFD-1
        location:
          description: The stock location for this order item.
          type: string
          readOnly: true
        unit_price:
          $ref: '#/components/schemas/OrderPriceData'
        value:
          $ref: '#/components/schemas/OrderPriceData'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/DiscountData'
        links:
          type: object
        meta:
          type: object
          properties:
            display_price:
              type: object
              properties:
                with_tax:
                  $ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
                without_tax:
                  $ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
                tax:
                  $ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
                discount:
                  $ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
                without_discount:
                  $ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
                discounts:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      amount:
                        type: number
                        examples:
                        - -1000
                      currency:
                        type: string
                        examples:
                        - USD
                      formatted:
                        type: string
                        examples:
                        - -$1.00
                      constituents:
                        type: object
                        description: Detailed breakdown of discount constituents by ID
                        additionalProperties:
                          type: object
                          properties:
                            amount:
                              type: number
                              description: The discount amount
                            currency:
                              type: string
                              description: The currency code
                            formatted:
                              type: string
                              description: The formatted discount amount
                original_price:
                  description: The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product).
                  $ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
            timestamps:
              $ref: '#/components/schemas/Timestamps'
        relationships:
          type: object
          properties:
            cart_item:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      description: The type represents the object being returned.
                      type: string
                      examples:
                      - order_item
                    id:
                      description: The unique identifier for this item.
                      type: string
                      format: uuid
                      readOnly: true
                      examples:
                      - 5601a4b1-9d13-42d3-8fb7-03b35169d1b6
            taxes:
              description: Related tax items.
              type: object
              properties:
                data:
                  oneOf:
                  - type: 'null'
                  - type: array
                    items:
                      $ref: '#/components/schemas/RelationshipItem'
            promotions:
              description: Related promotions.
              type: object
              properties:
                data:
                  oneOf:
                  - type: 'null'
                  - type: array
                    items:
                      $ref: '#/components/schemas/RelationshipItem'
        catalog_id:
          description: The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.
          type: string
          examples:
          - default
        catalog_source:
          description: The catalog source. Always `pim` or `legacy`.
          type: string
          examples:
          - pim
          - legacy
        bundle_configuration:
          description: Configuration for bundle products.
          type: object
          properties:
            selected_options:
              type: object
              additionalProperties:
                type: object
                additionalProperties:
                  type: number
            component_products:
              description: Array of component products for bundle configuration
              type: array
              items:
                type: object
                properties:
                  id:
                    description: Component product ID
                    type: string
                  type:
                    description: Component product type
                    type: string
                  attributes:
                    description: Product attributes as a generic object
                    type: object
                    additionalProperties: true
                  meta:
                    description: Product metadata as a generic object
                    type: object
                    additionalProperties: true
                  price:
                    description: Product price information as a generic object
                    type: object
                    additionalProperties: true
                  relationships:
                    description: Product relationships as a generic object
                    type: object
                    additionalProperties: true
        components:
          description: Components of the bundle product.
          type: object
          additionalProperties:
            type: object
            properties:
              name:
                type: string
              options:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    quantity:
                      type: number
                    type:
                      type: string
        custom_inputs:
          description: Custom inputs for the order item as a generic object
          type: object
          additionalProperties: true
        custom_attributes:
          description: Custom attributes attached to the order item.
          readOnly: true
          $ref: '#/components/schemas/CustomAttributes'
        shipping_group_id:
          description: The shipping group ID for the order item
          type: string
        promotion_source:
          description: The promotion source for the order item
          type: string
        subscription_configuration:
          description: Subscription configuration for the order item
          type: object
          properties:
            plan:
              description: Subscription plan details
              type: string
            pricing_option:
              description: Pricing option for the subscription
              type: string
    DiscountFormattedPriceData:
      title: DiscountFormattedPriceData
      type: object
      properties:
        amount:
          description: The discount amount. Must be non-positive (zero or negative).
          type: number
          maximum: 0
          examples:
          - -1000
          - 0
        currency:
          description: The currency set for this amount.
          type: string
          examples:
          - USD
        formatted:
          description: The formatted total based on the amount and currency.
          type: string
          examples:
          - -$10.00
          - $0.00
    FormattedPriceData:
      title: FormattedPriceData
      type: object
      properties:
        amount:
          description: The raw total.
          type: number
          examples:
          - 10000
        currency:
          description: The currency set for this amount.
          type: string
          examples:
          - USD
        formatted:
          description: The formatted total based on the amount and currency.
          type: string
          examples:
          - $10.00
    Response.ErrorItem:
      type: object
      required:
      - status
      - title
      properties:
        title:
          type: string
          description: A brief summary of the error.
          examples:
          - Bad Request
        status:
          type:
          - string
          - integer
          description: The HTTP response code of the error.
          examples:
          - '400'
        detail:
          type: string
          description: Optional additional detail about the error.
          examples:
          - The field 'name' is required
        source:
          type: string
          description: The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity').
        meta:
          type: object
          description: Additional metadata associated with the error. May include arbitrary keys.
          properties:
            id:
              type: string
              description: The resource id associated with the error
            ids:
              type: array
              items:
                type: string
                description: The resource ids associated with the error
            item_ids:
              type: array
              items:
                type: string
                description: The cart_item ids associated with the error
            shipping_group_id:
              type: string
              description: The shipping group id associated with the error
            shipping_group_ids:
              type: array
              items:
                type: string
                description: The shipping group ids associated with the error
            cart_id:
              type: string
              description: The cart id associated with the error
            code:
              type: string
              description: The code associated with the error.
            order_id:
              type: string
              description: The order id associated with the error.
            sku:
              type: string
              description: The SKU associated with the error.
            email:
              type: string
              format: email
              description: The email address associated with the error.
            component_product_id:
              type: string
              format: uuid
              description: The component product ID associated with the error.
            error-meta-key:
              type: string
              description: Custom error metadata key used for additional error context (e.g., in payment rejections).
            value:
              description: The value associated with the error.
              oneOf:
              - type: string
              - type: integer
              - type: boolean
              - type: object
                additionalProperties: true
              - type: array
    Timestamps:
      type: object
      properties:
        created_at:
          description: The date this was created.
          type: string
        updated_at:
          description: The date this was last updated.
          type: string
    ShippingAddress:
      title: ShippingAddress
      description: 'Shipping address information. You must specify at least one of region (state/province) or county.

        '
      allOf:
      - anyOf:
        - $ref: '#/components/schemas/AddressWithRegion'
        - $ref: '#/components/schemas/AddressWithCounty'
      - type: object
        properties:
          phone_number:
            description: Phone number of the shipping recipient.
            type: string
          instructions:
            description: Delivery instructions.
            type: string
      examples:
      - first_name: John
        last_name: Doe
        line_1: 1 Sunny Street
        line_2: Apartment 123
        city: Los Angeles
        postcode: '92802'
        region: CA
        country: US
        instructions: Please leave on porch
      - first_name: Jane
        last_name: Smith
        line_1: 123 Main Street
        city: London
        postcode: SW1A 1AA
        county: Greater London
        country: GB
        phone_number: +44 20 7946 0958
    RelationshipItem:
      title: RelationshipItem
      description: Relationship data entry
      required:
      - type
      - id
      type: object
      properties:
        type:
          description: The type of related resource.
          type: string
        id:
          description: The ID of the related resource.
          type: string
          format: uuid
    AddressWithRegion:
      title: Address with Region
      allOf:
      - $ref: '#/components/schemas/AddressCommon'
      - type: object
        required:
        - region
        properties:
          region:
            description: State, province, or region of the address.
            type: string
    ShippingPriceRequest:
      type: object
      properties:
        total:
          type: number
        base:
          type: number
        tax:
          type: number
        fees:
          type: number
        discount:
          type: number
    DiscountData:
      title: DiscountData
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/OrderPriceData'
        code:
          type: string
        id:
          type: string
          format: uuid
          readOnly: true
        promotion_source:
          type: string
          description: The source or origin of the promotion, if applicable.
        is_cart_discount:
          type: boolean
          description: Indicates whether the discount applies to the entire cart.
        ordinal:
          type: integer
          description: Order in which the discount was applied.
    CreateShippingGroupRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              const: shipping_group
            shipping_type:
              type: string
            tracking_reference:
              type: string
            external_ref:
              description: An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.
              type: string
              maxLength: 64
            shipping_price:
 

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-cart-shipping-groups-api-openapi.yml