Commerce Layer Payments API

openapi: 3.0.1
info:
  title: Commerce Layer Core API
  description: >-
    Commerce Layer is a headless, composable commerce platform. The Core API is
    100% compliant with the JSON:API specification (v1.0) and supports compound
    documents, sparse fieldsets, resource linking, filtering, sorting, and
    pagination. All requests are authenticated with an OAuth2 Bearer access
    token obtained from https://auth.commercelayer.io/oauth/token, and access
    tokens may be scoped to a market or stock location. Resources are served
    under the organization subdomain at https://{organization}.commercelayer.io/api
    using the application/vnd.api+json content type.
  termsOfService: https://commercelayer.io/legal/terms-of-service
  contact:
    name: Commerce Layer Support
    url: https://commercelayer.io/contact
  version: '4.0'
servers:
  - url: https://{organization}.commercelayer.io/api
    description: Organization-scoped Core API endpoint
    variables:
      organization:
        default: yourdomain
        description: Your Commerce Layer organization subdomain (slug).
security:
  - bearerAuth: []
tags:
  - name: SKUs
    description: Stock keeping units describing the product variations being sold.
  - name: Prices
    description: Prices belonging to price lists, associated with SKUs.
  - name: Stock Items
    description: Stock quantities for a SKU at a given stock location.
  - name: Orders
    description: Shopping carts and orders and their checkout lifecycle.
  - name: Line Items
    description: Line items belonging to an order.
  - name: Customers
    description: Customer accounts.
  - name: Addresses
    description: Billing and shipping addresses.
  - name: Shipments
    description: Order shipments and fulfillment.
  - name: Payment Methods
    description: Payment methods available for orders.
  - name: Markets
    description: Markets binding price list, inventory model, and merchant.
  - name: Promotions
    description: Discounts, free shipping, free gifts, and other promotions.
  - name: Webhooks
    description: Event subscriptions delivering signed callbacks.
paths:
  /skus:
    get:
      operationId: listSkus
      tags: [SKUs]
      summary: List all SKUs
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: A list of SKU resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/SkuList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createSku
      tags: [SKUs]
      summary: Create a SKU
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/SkuData'
      responses:
        '201':
          description: The created SKU resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/SkuData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /skus/{skuId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getSku
      tags: [SKUs]
      summary: Retrieve a SKU
      responses:
        '200':
          description: The requested SKU resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/SkuData'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSku
      tags: [SKUs]
      summary: Update a SKU
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/SkuData'
      responses:
        '200':
          description: The updated SKU resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/SkuData'
    delete:
      operationId: deleteSku
      tags: [SKUs]
      summary: Delete a SKU
      responses:
        '204':
          description: The SKU was deleted.
  /prices:
    get:
      operationId: listPrices
      tags: [Prices]
      summary: List all prices
      responses:
        '200':
          description: A list of price resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createPrice
      tags: [Prices]
      summary: Create a price
      responses:
        '201':
          description: The created price resource.
  /prices/{priceId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getPrice
      tags: [Prices]
      summary: Retrieve a price
      responses:
        '200':
          description: The requested price resource.
    patch:
      operationId: updatePrice
      tags: [Prices]
      summary: Update a price
      responses:
        '200':
          description: The updated price resource.
    delete:
      operationId: deletePrice
      tags: [Prices]
      summary: Delete a price
      responses:
        '204':
          description: The price was deleted.
  /stock_items:
    get:
      operationId: listStockItems
      tags: [Stock Items]
      summary: List all stock items
      responses:
        '200':
          description: A list of stock item resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createStockItem
      tags: [Stock Items]
      summary: Create a stock item
      responses:
        '201':
          description: The created stock item resource.
  /stock_items/{stockItemId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getStockItem
      tags: [Stock Items]
      summary: Retrieve a stock item
      responses:
        '200':
          description: The requested stock item resource.
    patch:
      operationId: updateStockItem
      tags: [Stock Items]
      summary: Update a stock item
      responses:
        '200':
          description: The updated stock item resource.
    delete:
      operationId: deleteStockItem
      tags: [Stock Items]
      summary: Delete a stock item
      responses:
        '204':
          description: The stock item was deleted.
  /orders:
    get:
      operationId: listOrders
      tags: [Orders]
      summary: List all orders
      responses:
        '200':
          description: A list of order resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createOrder
      tags: [Orders]
      summary: Create an order
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/OrderData'
      responses:
        '201':
          description: The created order resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrderData'
  /orders/{orderId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getOrder
      tags: [Orders]
      summary: Retrieve an order
      responses:
        '200':
          description: The requested order resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrderData'
    patch:
      operationId: updateOrder
      tags: [Orders]
      summary: Update an order
      description: >-
        Update order attributes or trigger order state transitions (e.g.
        _place, _approve, _cancel) by setting the corresponding trigger
        attribute to true.
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/OrderData'
      responses:
        '200':
          description: The updated order resource.
    delete:
      operationId: deleteOrder
      tags: [Orders]
      summary: Delete an order
      responses:
        '204':
          description: The order was deleted.
  /line_items:
    get:
      operationId: listLineItems
      tags: [Line Items]
      summary: List all line items
      responses:
        '200':
          description: A list of line item resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createLineItem
      tags: [Line Items]
      summary: Create a line item
      responses:
        '201':
          description: The created line item resource.
  /line_items/{lineItemId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getLineItem
      tags: [Line Items]
      summary: Retrieve a line item
      responses:
        '200':
          description: The requested line item resource.
    patch:
      operationId: updateLineItem
      tags: [Line Items]
      summary: Update a line item
      responses:
        '200':
          description: The updated line item resource.
    delete:
      operationId: deleteLineItem
      tags: [Line Items]
      summary: Delete a line item
      responses:
        '204':
          description: The line item was deleted.
  /customers:
    get:
      operationId: listCustomers
      tags: [Customers]
      summary: List all customers
      responses:
        '200':
          description: A list of customer resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createCustomer
      tags: [Customers]
      summary: Create a customer
      responses:
        '201':
          description: The created customer resource.
  /customers/{customerId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getCustomer
      tags: [Customers]
      summary: Retrieve a customer
      responses:
        '200':
          description: The requested customer resource.
    patch:
      operationId: updateCustomer
      tags: [Customers]
      summary: Update a customer
      responses:
        '200':
          description: The updated customer resource.
    delete:
      operationId: deleteCustomer
      tags: [Customers]
      summary: Delete a customer
      responses:
        '204':
          description: The customer was deleted.
  /addresses:
    get:
      operationId: listAddresses
      tags: [Addresses]
      summary: List all addresses
      responses:
        '200':
          description: A list of address resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createAddress
      tags: [Addresses]
      summary: Create an address
      responses:
        '201':
          description: The created address resource.
  /addresses/{addressId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getAddress
      tags: [Addresses]
      summary: Retrieve an address
      responses:
        '200':
          description: The requested address resource.
    patch:
      operationId: updateAddress
      tags: [Addresses]
      summary: Update an address
      responses:
        '200':
          description: The updated address resource.
    delete:
      operationId: deleteAddress
      tags: [Addresses]
      summary: Delete an address
      responses:
        '204':
          description: The address was deleted.
  /shipments:
    get:
      operationId: listShipments
      tags: [Shipments]
      summary: List all shipments
      responses:
        '200':
          description: A list of shipment resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
  /shipments/{shipmentId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getShipment
      tags: [Shipments]
      summary: Retrieve a shipment
      responses:
        '200':
          description: The requested shipment resource.
    patch:
      operationId: updateShipment
      tags: [Shipments]
      summary: Update a shipment
      description: >-
        Update shipment attributes or trigger shipment state transitions (e.g.
        _ship, _deliver) by setting the corresponding trigger attribute.
      responses:
        '200':
          description: The updated shipment resource.
  /payment_methods:
    get:
      operationId: listPaymentMethods
      tags: [Payment Methods]
      summary: List all payment methods
      responses:
        '200':
          description: A list of payment method resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createPaymentMethod
      tags: [Payment Methods]
      summary: Create a payment method
      responses:
        '201':
          description: The created payment method resource.
  /payment_methods/{paymentMethodId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getPaymentMethod
      tags: [Payment Methods]
      summary: Retrieve a payment method
      responses:
        '200':
          description: The requested payment method resource.
    patch:
      operationId: updatePaymentMethod
      tags: [Payment Methods]
      summary: Update a payment method
      responses:
        '200':
          description: The updated payment method resource.
    delete:
      operationId: deletePaymentMethod
      tags: [Payment Methods]
      summary: Delete a payment method
      responses:
        '204':
          description: The payment method was deleted.
  /markets:
    get:
      operationId: listMarkets
      tags: [Markets]
      summary: List all markets
      responses:
        '200':
          description: A list of market resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createMarket
      tags: [Markets]
      summary: Create a market
      responses:
        '201':
          description: The created market resource.
  /markets/{marketId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getMarket
      tags: [Markets]
      summary: Retrieve a market
      responses:
        '200':
          description: The requested market resource.
    patch:
      operationId: updateMarket
      tags: [Markets]
      summary: Update a market
      responses:
        '200':
          description: The updated market resource.
    delete:
      operationId: deleteMarket
      tags: [Markets]
      summary: Delete a market
      responses:
        '204':
          description: The market was deleted.
  /promotions:
    get:
      operationId: listPromotions
      tags: [Promotions]
      summary: List all promotions
      responses:
        '200':
          description: A list of promotion resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
  /promotions/{promotionId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getPromotion
      tags: [Promotions]
      summary: Retrieve a promotion
      responses:
        '200':
          description: The requested promotion resource.
  /webhooks:
    get:
      operationId: listWebhooks
      tags: [Webhooks]
      summary: List all webhooks
      responses:
        '200':
          description: A list of webhook resources.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createWebhook
      tags: [Webhooks]
      summary: Create a webhook
      description: >-
        Subscribe to an event topic. Each time the subscribed event occurs,
        Commerce Layer triggers a POST request to the callback_url; the topic
        is sent in the X-CommerceLayer-Topic header.
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/WebhookData'
      responses:
        '201':
          description: The created webhook resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookData'
  /webhooks/{webhookId}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getWebhook
      tags: [Webhooks]
      summary: Retrieve a webhook
      responses:
        '200':
          description: The requested webhook resource.
    patch:
      operationId: updateWebhook
      tags: [Webhooks]
      summary: Update a webhook
      responses:
        '200':
          description: The updated webhook resource.
    delete:
      operationId: deleteWebhook
      tags: [Webhooks]
      summary: Delete a webhook
      responses:
        '204':
          description: The webhook was deleted.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth2 access token obtained from
        https://auth.commercelayer.io/oauth/token (client_credentials,
        password, authorization_code, refresh_token, or JWT bearer grant).
        Passed as Authorization: Bearer {access_token}. Tokens may carry a
        market or stock_location scope.
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      description: The resource unique identifier.
      schema:
        type: string
    PageNumber:
      name: page[number]
      in: query
      required: false
      description: The page of results to return (JSON:API pagination).
      schema:
        type: integer
        default: 1
    PageSize:
      name: page[size]
      in: query
      required: false
      description: Number of results per page (max 25, up to 25 by default).
      schema:
        type: integer
        default: 10
        maximum: 25
    Sort:
      name: sort
      in: query
      required: false
      description: Comma-separated list of fields to sort by; prefix with - for descending.
      schema:
        type: string
    Include:
      name: include
      in: query
      required: false
      description: Comma-separated list of relationships to side-load (compound documents).
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFound:
      description: The resource was not found.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
    UnprocessableEntity:
      description: Validation failed.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
    RateLimited:
      description: Too many requests; the rate limit was exceeded.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
  schemas:
    ResourceList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          type: object
    Resource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
        links:
          type: object
    Meta:
      type: object
      properties:
        record_count:
          type: integer
        page_count:
          type: integer
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              detail:
                type: string
              code:
                type: string
              status:
                type: string
    SkuList:
      allOf:
        - $ref: '#/components/schemas/ResourceList'
    SkuData:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Sku'
    Sku:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [skus]
        attributes:
          type: object
          properties:
            code:
              type: string
              description: A unique SKU code (EAN, UPC, or any custom code).
            name:
              type: string
            description:
              type: string
            image_url:
              type: string
            pieces_per_pack:
              type: integer
            weight:
              type: number
            unit_of_weight:
              type: string
              enum: [gr, oz, lb]
            hs_tariff_number:
              type: string
            do_not_ship:
              type: boolean
            do_not_track:
              type: boolean
            metadata:
              type: object
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
        relationships:
          type: object
    OrderData:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Order'
    Order:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [orders]
        attributes:
          type: object
          properties:
            number:
              type: integer
            status:
              type: string
              enum: [draft, pending, placed, approved, cancelled]
            payment_status:
              type: string
              enum: [unpaid, authorized, paid, voided, refunded, free, partially_authorized, partially_paid, partially_refunded, partially_voided]
            fulfillment_status:
              type: string
              enum: [unfulfilled, in_progress, fulfilled, not_required]
            currency_code:
              type: string
            total_amount_cents:
              type: integer
            customer_email:
              type: string
            language_code:
              type: string
            _place:
              type: boolean
              description: Trigger attribute to place the order.
            _approve:
              type: boolean
              description: Trigger attribute to approve the order.
            metadata:
              type: object
        relationships:
          type: object
    WebhookData:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Webhook'
    Webhook:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [webhooks]
        attributes:
          type: object
          properties:
            name:
              type: string
            topic:
              type: string
              description: The event topic, e.g. orders.place or orders.approve.
            callback_url:
              type: string
              description: The endpoint that receives the POST callback.
            include_resources:
              type: array
              items:
                type: string
            circuit_state:
              type: string
              enum: [closed, open]
              description: Circuit breaker state; opens after repeated delivery failures.
            circuit_failure_count:
              type: integer
            shared_secret:
              type: string
              description: Secret used to sign callback payloads.
            metadata:
              type: object
        relationships:
          type: object