openapi: 3.1.0
info:
title: Commerce Layer addresses links API
version: 7.10.1
contact:
name: API Support
url: https://commercelayer.io
email: support@commercelayer.io
description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
description: API
- url: https://core.commercelayer.io/users/sign_in
description: Sign in
- url: https://docs.commercelayer.io/api
description: API reference
security:
- bearerAuth: []
tags:
- name: links
description: resource type
paths:
/links:
get:
operationId: GET/links
summary: List all links
description: List all links
tags:
- links
responses:
'200':
description: A list of link objects
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/linkResponseList'
post:
operationId: POST/links
summary: Create a link
description: Create a link
tags:
- links
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/linkCreate'
responses:
'201':
description: The created link object
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/linkResponse'
/links/{linkId}:
get:
operationId: GET/links/linkId
summary: Retrieve a link
description: Retrieve a link
tags:
- links
parameters:
- name: linkId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The link object
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/linkResponse'
patch:
operationId: PATCH/links/linkId
summary: Update a link
description: Update a link
tags:
- links
parameters:
- name: linkId
in: path
schema:
type: string
required: true
description: The resource's id
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/linkUpdate'
responses:
'200':
description: The updated link object
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/linkResponse'
delete:
operationId: DELETE/links/linkId
summary: Delete a link
description: Delete a link
tags:
- links
parameters:
- name: linkId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'204':
description: No content
/orders/{orderId}/links:
get:
operationId: GET/orderId/links
summary: Retrieve the links associated to the order
description: Retrieve the links associated to the order
tags:
- links
parameters:
- name: orderId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The links associated to the order
/sku_lists/{skuListId}/links:
get:
operationId: GET/skuListId/links
summary: Retrieve the links associated to the SKU list
description: Retrieve the links associated to the SKU list
tags:
- links
parameters:
- name: skuListId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The links associated to the SKU list
/skus/{skuId}/links:
get:
operationId: GET/skuId/links
summary: Retrieve the links associated to the SKU
description: Retrieve the links associated to the SKU
tags:
- links
parameters:
- name: skuId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The links associated to the SKU
components:
schemas:
satispayPayment:
type: object
properties:
data:
type: object
required:
- type
- attributes
properties:
type:
type: string
description: The resource's type
enum:
- satispay_payments
attributes:
type: object
properties:
payment_id:
type: string
description: The payment unique identifier.
example: xxxx-yyyy-zzzz
nullable: true
flow:
type: string
description: The Satispay payment flow, inspect gateway API details for more information.
example: MATCH_CODE
nullable: true
status:
type: string
description: The Satispay payment status.
example: PENDING
nullable: true
redirect_url:
type: string
description: The url to redirect the customer after the payment flow is completed.
example: http://commercelayer.dev/satispay/redirect
nullable: true
payment_url:
type: string
description: Redirect url to the payment page.
example: https://online.satispay.com/pay/xxxx-yyyy-zzzz?redirect_url={redirect_url}
nullable: true
payment_response:
type: object
description: The Satispay payment response, used to fetch internal data.
example:
foo: bar
nullable: true
payment_instrument:
type: object
description: Information about the payment instrument used in the transaction.
example:
issuer: cl bank
card_type: visa
nullable: true
created_at:
type: string
description: Time at which the resource was created.
example: '2018-01-01T12:00:00.000Z'
nullable: false
updated_at:
type: string
description: Time at which the resource was last updated.
example: '2018-01-01T12:00:00.000Z'
nullable: false
reference:
type: string
description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
example: ANY-EXTERNAL-REFEFERNCE
nullable: true
reference_origin:
type: string
description: Any identifier of the third party system that defines the reference code.
example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
nullable: true
metadata:
type: object
description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
example:
foo: bar
nullable: true
relationships:
type: object
properties:
order:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- orders
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
payment_gateway:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- payment_gateways
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
event_stores:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- event_stores
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
wireTransfer:
type: object
properties:
data:
type: object
required:
- type
- attributes
properties:
type:
type: string
description: The resource's type
enum:
- wire_transfers
attributes:
type: object
properties:
payment_instrument:
type: object
description: Information about the payment instrument used in the transaction.
example:
issuer: cl bank
card_type: visa
nullable: true
created_at:
type: string
description: Time at which the resource was created.
example: '2018-01-01T12:00:00.000Z'
nullable: false
updated_at:
type: string
description: Time at which the resource was last updated.
example: '2018-01-01T12:00:00.000Z'
nullable: false
reference:
type: string
description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
example: ANY-EXTERNAL-REFEFERNCE
nullable: true
reference_origin:
type: string
description: Any identifier of the third party system that defines the reference code.
example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
nullable: true
metadata:
type: object
description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
example:
foo: bar
nullable: true
relationships:
type: object
properties:
order:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- orders
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
event_stores:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- event_stores
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
capture:
type: object
properties:
data:
type: object
required:
- type
- attributes
properties:
type:
type: string
description: The resource's type
enum:
- captures
attributes:
type: object
properties:
number:
type: string
description: The transaction number, auto generated.
example: 42/T/001
nullable: false
type:
type: string
description: The transaction's type.
example: authorizations
nullable: false
enum:
- authorizations
- voids
- captures
- refunds
payment_method_type:
type: string
description: Information about the payment method used in the transaction.
example: credit card
nullable: true
currency_code:
type: string
description: The international 3-letter currency code as defined by the ISO 4217 standard, inherited from the associated order.
example: EUR
nullable: false
amount_cents:
type: integer
description: The transaction amount, in cents.
example: 1500
nullable: false
amount_float:
type: number
description: The transaction amount, float.
example: 15.0
nullable: false
formatted_amount:
type: string
description: The transaction amount, formatted.
example: €15,00
nullable: false
succeeded:
type: boolean
description: Indicates if the transaction is successful.
example: false
nullable: false
message:
type: string
description: The message returned by the payment gateway.
example: Accepted
nullable: true
error_code:
type: string
description: The error code, if any, returned by the payment gateway.
example: '00001'
nullable: true
error_detail:
type: string
description: The error detail, if any, returned by the payment gateway.
example: Already settled
nullable: true
token:
type: string
description: The token identifying the transaction, returned by the payment gateway.
example: xxxx-yyyy-zzzz
nullable: true
gateway_transaction_id:
type: string
description: The ID identifying the transaction, returned by the payment gateway.
example: xxxx-yyyy-zzzz
nullable: true
created_at:
type: string
description: Time at which the resource was created.
example: '2018-01-01T12:00:00.000Z'
nullable: false
updated_at:
type: string
description: Time at which the resource was last updated.
example: '2018-01-01T12:00:00.000Z'
nullable: false
reference:
type: string
description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
example: ANY-EXTERNAL-REFEFERNCE
nullable: true
reference_origin:
type: string
description: Any identifier of the third party system that defines the reference code.
example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
nullable: true
metadata:
type: object
description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
example:
foo: bar
nullable: true
refund_amount_cents:
type: integer
description: The amount to be refunded, in cents.
example: 500
nullable: true
refund_amount_float:
type: number
description: The amount to be refunded, float.
example: 5.0
nullable: true
formatted_refund_amount:
type: string
description: The amount to be refunded, formatted.
example: €5,00
nullable: true
refund_balance_cents:
type: integer
description: The balance to be refunded, in cents.
example: 1000
nullable: true
refund_balance_float:
type: number
description: The balance to be refunded, float.
example: 10.0
nullable: true
formatted_refund_balance:
type: string
description: The balance to be refunded, formatted.
example: €10,00
nullable: true
relationships:
type: object
properties:
order:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- orders
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
payment_source:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- adyen_payments
- axerve_payments
- braintree_payments
- checkout_com_payments
- external_payments
- klarna_payments
- paypal_payments
- satispay_payments
- stripe_payments
- wire_transfers
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
oneOf:
- $ref: '#/components/schemas/adyenPayment'
- $ref: '#/components/schemas/axervePayment'
- $ref: '#/components/schemas/braintreePayment'
- $ref: '#/components/schemas/checkoutComPayment'
- $ref: '#/components/schemas/externalPayment'
- $ref: '#/components/schemas/klarnaPayment'
- $ref: '#/components/schemas/paypalPayment'
- $ref: '#/components/schemas/satispayPayment'
- $ref: '#/components/schemas/stripePayment'
- $ref: '#/components/schemas/wireTransfer'
attachments:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- attachments
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
events:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- events
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
event_stores:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- event_stores
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
reference_authorization:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- authorizations
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
refunds:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- refunds
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
return:
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- returns
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
order:
type: object
properties:
data:
type: object
required:
- type
- attributes
properties:
type:
type: string
description: The resource's type
enum:
- orders
attributes:
type: object
properties:
number:
type: string
description: The order identifier. Can be specified if unique within the organization (for enterprise plans only), default to numeric ID otherwise. Cannot be passed by sales channels.
example: '1234'
nullable: true
affiliate_code:
type: string
description: The affiliate code, if any, to track commissions using any third party services.
example: xxxx-yyyy-zzzz
nullable: true
autorefresh:
type: boolean
description: Save this attribute as 'false' if you want prevent the order to be refreshed automatically at each change (much faster).
example: true
nullable: true
place_async:
type: boolean
description: Save this attribute as 'true' if you want perform the place asynchronously. Payment errors, if any, will be collected afterwards.
example: true
nullable: true
status:
type: string
description: The order status. One of 'draft' (default), 'pending', 'editing', 'placing', 'placed', 'approved', or 'cancelled'.
example: draft
nullable: false
enum:
- draft
- pending
- editing
- placing
- placed
- approved
- cancelled
payment_status:
type: string
description: The order payment status. One of 'unpaid' (default), 'authorized', 'partially_authorized', 'paid', 'partially_paid', 'voided', 'partially_voided', 'refunded', 'partially_refunded', or 'free'.
example: unpaid
nullable: false
enum:
- unpaid
- authorized
- partially_authorized
- paid
- partially_paid
- voided
- partially_voided
- refunded
- partially_refunded
- free
fulfillment_status:
type: string
description: The order fulfillment status. One of 'unfulfilled' (default), 'in_progress', 'fulfilled', or 'not_required'.
example: unfulfilled
nullable: false
enum:
- unfulfilled
- in_progress
- fulfilled
- not_required
guest:
type: boolean
description: Indicates if the order has been placed as guest.
example: true
nullable: true
editable:
type: boolean
description: Indicates if the order can be edited.
example: true
nullable: true
customer_email:
type: string
description: The email address of the associated customer. When creating or updating an order, this is a shortcut to find or create the associated customer by email.
example: john@example.com
nullable: true
customer_type:
type: string
description: The type of the associated customer. One of 'new', or 'returning'.
example: returning
nullable: true
enum:
- new
- returning
language_code:
type: string
description: The preferred language code (ISO 639-1) to be used when communicating with the customer. This can be useful when sending the order to 3rd party marketing tools and CRMs. If the language is supported, the hosted checkout will be localized accordingly.
example: it
nullable: true
currency_code:
type: string
description: The international 3-letter currency code as defined by the ISO 4217 standard, automatically inherited from the order's market.
example: EUR
nullable: true
tax_included:
type: boolean
description: Indicates if taxes are included in the order amounts, automatically inherited from the order's price list.
example: true
nullable: true
tax_rate:
type: number
description: The tax rate for this order (if calculated).
example: 0.22
nullable: true
freight_taxable:
type: boolean
description: Indicates if taxes are applied to shipping costs.
example: true
nullable: true
payment_method_taxable:
type: boolean
description: Indicates if taxes are applied to payment methods costs.
example: true
nullable: true
adjustment_taxable:
type: boolean
description: Indicates if taxes are applied to positive adjustments.
example: true
nullable: true
gift_card_taxable:
type: boolean
description: Indicates if taxes are applied to purchased gift cards.
example: false
nullable: true
requires_billing_info:
type: boolean
description: Indicates if the billing address associated to this order requires billing info to be present.
example: false
nullable: true
country_code:
type: string
description: The international 2-letter country code as defined by the ISO 3166-1 standard, automatically inherited from the order's shipping or billing addresses.
example: IT
nullable: true
shipping_country_code_lock:
type: string
description: The country code that you want the shipping address to be locked to. This can be useful to make sure the shipping address belongs to a given shipping country, e.g. the one selected in a country selector page. Not relevant if order contains only digital products.
example: IT
nullable: true
coupon_code:
type: string
description: The coupon code to be used for the order. If valid, it triggers a promotion adding a discount line item to the order.
example: SUMMERDISCOUNT
nullable: true
gift_card_code:
type: string
description: The gift card code (at least the first 8 characters) to be used for the order. If valid, it uses the gift card balance to pay for the order.
example: cc92c23e-967e-48b2-a323-59add603301f
nullable: true
subtotal_amount_cents:
type: integer
description: The sum of all the SKU line items total amounts, in cents.
example: 5000
# --- truncated at 32 KB (194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-links-api-openapi.yml