Retrieves a cart by its ID.

GET

checkout

carts

{id}

curl -X GET \
 /checkout/carts/{id} \
 --header "Authorization: Bearer <token>"

{
  "id": "c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b",
  "status": "<any>",
  "customer": "c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b",
  "customerEmail": {
    "id": "00000000-0000-0000-0000-000000000000",
    "email": "john.doe@example.com",
    "receiverName": "John Doe",
    "type": "TYPE_COMPANY",
    "default": "true"
  },
  "invoiceAddress": {
    "id": "<string>",
    "vatId": "DE123456789",
    "type": "TYPE_DEFAULT",
    "default": "true",
    "status": "active",
    "city": "Berlin",
    "zip": "12345",
    "street": "Musterstraße",
    "houseNumber": "1a",
    "countryCode": "DE",
    "companyName": "ACME Inc.",
    "salutation": "Herr",
    "addition": "c/o John Doe",
    "costCentre": "123456789",
    "firstName": "John",
    "lastName": "Doe"
  },
  "paymentMethod": "c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "redirectUrl": "<string>",
  "items": [
    {
      "id": "<string>",
      "product": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "name": "Basic",
        "description": "For small teams.",
        "type": "product",
        "invoiceVisibility": "always",
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "pricePlan": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "type": "<any>",
        "applyTrial": true,
        "payInAdvance": true,
        "proRata": true,
        "freeUnits": {},
        "billingInterval": "1M",
        "showPricePerInterval": "1M",
        "currencyCode": {},
        "price": {
          "amount": 123,
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00",
          "tenantId": "<string>"
        }
      },
      "quantity": {},
      "type": "product",
      "periods": [
        {
          "id": "<string>",
          "contractPeriodCount": 123,
          "contractPeriod": {},
          "cancellationPeriod": {}
        }
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "customer": {
      "id": "00000000-0000-0000-0000-000000000000",
      "customerNumber": "CUSTOMER-000",
      "timeZone": "Europe/Berlin",
      "firstName": "John",
      "lastName": "Doe",
      "currencyCode": "EUR",
      "companyName": "Acme Inc.",
      "datevId": "123456789",
      "status": "STATUS_ACTIVE"
    },
    "paymentMethod": {
      "id": "<string>",
      "gatewayName": "wallet",
      "type": "sepa_debit",
      "default": true,
      "status": "active",
      "enabled": true,
      "name": "<string>",
      "creationDate": "2023-11-07T05:31:56Z",
      "expirationDate": "2023-11-07T05:31:56Z",
      "card": {
        "brand": "Visa",
        "last4": "4242",
        "expMonth": 12,
        "expYear": 2022,
        "cardHolder": "Max Mustermann"
      },
      "sepaDebit": {
        "iban": "DE8937*********3232",
        "bic": "COBADEFFXXX",
        "mandateReference": "MNDT-2021-123456",
        "signingDate": "2021-01-01T00:00:00+00:00"
      },
      "paypal": {
        "email": "max@mustermann.de",
        "billingAgreementId": "I-1J5gqz2eZvKYlo2C2X2X2X2X"
      }
    },
    "type": "TYPE_INVOICE",
    "currencyCode": "EUR",
    "number": "RE-0000000001",
    "status": "STATUS_DRAFT",
    "finalizationDate": "2023-11-07T05:31:56Z",
    "dueDate": "2023-11-07T05:31:56Z",
    "dunningLevel": 123,
    "dunningStatus": "none",
    "payDate": "2023-11-07T05:31:56Z",
    "invoiceAddress": "<any>",
    "internalNote": "This invoice is with a special discount.",
    "netAmount": {},
    "grossAmount": {},
    "taxAmount": {},
    "customFields": {
      "field1": "value1",
      "field2": "value2"
    },
    "unpaidAmount": {}
  },
  "subscription": {
    "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
    "externalId": "<string>",
    "number": "S-00000001",
    "name": "Fitness M",
    "billingGroup": {},
    "periods": [
      {
        "id": "<string>",
        "contractPeriodCount": 123,
        "contractPeriod": {},
        "cancellationPeriod": {}
      }
    ],
    "status": "<any>",
    "activatedAt": "2021-01-01T00:00:00+00:00",
    "poNumber": "PO-00000001",
    "contractDetails": {
      "contractStart": "2023-11-07T05:31:56Z",
      "contractEnd": "2023-11-07T05:31:56Z"
    },
    "trialEndsOn": "2021-01-01T00:00:00+00:00",
    "customFields": {
      "field1": "value1",
      "field2": "value2"
    },
    "nextBillingDate": "2023-11-07T05:31:56Z",
    "lastBillingAt": "2023-11-07T05:31:56Z",
    "partner": {
      "id": "ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b",
      "name": "John Doe",
      "number": "123456",
      "email": "partner@example.com"
    }
  },
  "metadata": {
    "yourKey": "value"
  },
  "transactions": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "type": "payment",
      "status": "<any>",
      "description": "Payment for invoice #123",
      "documentNumber": "123456789",
      "currencyCode": "EUR",
      "amount": 500,
      "refundedAmount": 123,
      "chargedAmount": 500,
      "feeAmount": 50,
      "createdAt": "2023-11-07T05:31:56Z",
      "paidAt": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

Value for the Authorization header parameter.

Path Parameters

string

required

Cart identifier

Response

200

application/json

Cart resource

string

Example:

"c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b"

status

any

The status of the cart.

Possible values:

open: The cart is open and can be edited.
confirming: The cart is confirming and cannot be edited.

customer

object | null

The customer who owns the cart.

Example:

"c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b"

customerEmail

object | null

The customer email which is used for the cart.

invoiceAddress

object | null

paymentMethod

object | null

The payment method which should be used for the cart.

Example:

"c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b"

createdAt

string

updatedAt

string

completedAt

string | null

redirectUrl

string | null

items

object[]

The items of the cart.

items.id

string

items.product

object

items.product.type

enum<string>

required

The type of the product.

product: recurring billed product
charge: one-time billing
plan: plan specific product, which cannot be used as a normal product. Will be filtered out in any product lists.

Available options:

product,

charge,

plan

items.product.id

string

The unique identifier of the product.

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

items.product.name

string

The name of the product based on the current tenant language. This will be displayed on customer communication.

Example:

"Basic"

items.product.description

string | null

The description of the product based on the current tenant language.

Example:

"For small teams."

items.product.invoiceVisibility

enum<string>

Defines when the product should be displayed in the invoice.

always: The product is always displayed in the invoice.
only_if_charged: The product is only displayed in the invoice if it is charged.

Available options:

always,

only_if_charged

items.product.customFields

object | null

Custom fields for the entity. The keys are the field names and the values are the field values. They need to be configured under "/custom-fields" in the API documentation. The input is validated against the configuration. For more details see Custom Fields Guide

Example:

{ "field1": "value1", "field2": "value2" }

items.pricePlan

object | null

items.pricePlan.type

any

required

The type of the charge. This defines how the price is calculated.

Possible values:

flat_fee: A flat fee is charged, e.g. 10€ per month independent of the number of units.
volume: A volume based price is charged, e.g. 10€ for the first 10 units and 9€ for all units when the number of units is above 10. Useful for volume discounts.
percentage: A percentage of the total price is charged, e.g. 10% of the total price multiplied by the number of units. Useful for provisions.
per_unit: A price per unit is charged, e.g. 10€ per unit per billing interval. Useful for per seat based pricing.
tiered: A tiered price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for the next 10 units and 8€ per unit for all units above 20.
stair_step: A stair step price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for all units above 10.

items.pricePlan.currencyCode

object

required

The currency of the price

items.pricePlan.price

object

required

The price in the defined billing interval.

items.pricePlan.id

string

The unique identifier of the price plan.

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

items.pricePlan.applyTrial

boolean

default:true

If this is set to true, the price plan can be applied on a trial. If the product is in trial, and this is false, the price will be charged on subscription start, otherwise after trial.

Example:

true

items.pricePlan.payInAdvance

boolean | null

default:true

If this is set to true, the price will be charged in advance. If this is false, the price will be charged at the end of the billing interval.

Example:

true

items.pricePlan.proRata

boolean

If this is set to true, the price will be charged prorated when a partial billing interval is billed. This applies to measurements of type "recurring" or non-one-time billing intervals. For other measurements this parameter will be ignored.

items.pricePlan.freeUnits

object | null

The amount of free units. If null, no free units are available. Free units will be applied before passed to the price calculation and are available prorated. If the customer does not uses the free units during a billing period, they are not carried over to the next billing period. If the customer cancels the subscription before ending the billing period, the free units are only available prorated for the remaining billing period.

Example: You offer 2400 free units for 12 months and your price has a billing interval for 1 month. The customer cancels after 6 months. Only 1200 free units are available.

A price plan for a recurring product cannot have free units. Use a metered product instead.

A price plan related to a product of type charge cannot have free units.

items.pricePlan.billingInterval

object | null

The billing interval of the price plan. If null, this is a one-time charge. Billing intervals of null cannot be prorated.

Example:

"1M"

items.pricePlan.showPricePerInterval

object | null

Display the billed price per interval in customerfront or invoices. If null, the price will be shown per billing interval. Currently only available for billing intervals of months, years. Currently only allowed to show price per month (1M)

Example:

"1M"

items.quantity

object

items.type

enum<string>

default:product

Available options:

product

Example:

"product"

items.periods

object[]

items.createdAt

string

items.updatedAt

string

invoice

object | null

The invoice of the cart. If the cart total amount is zero, no invoice will be created.

invoice.id

string

The unique identifier of the invoice.

Example:

"00000000-0000-0000-0000-000000000000"

invoice.customer

object

The customer of the invoice.

invoice.paymentMethod

object | null

The payment method which should be used to fullfill the payment of the invoice.

invoice.paymentMethod.id

string

invoice.paymentMethod.gatewayName

enum<string>

Available options:

wallet,

sepa_debit,

stripe,

fake_provider,

paypal,

bank_transfer,

go_cardless,

testing

invoice.paymentMethod.type

enum<string> | null

Available options:

sepa_debit,

card,

paypal,

bank_transfer,

wallet,

fake_provider

invoice.paymentMethod.default

boolean

invoice.paymentMethod.status

enum<string>

default:active

Available options:

active,

action_required,

expired,

revoked,

gateway_unconfigured

Example:

"active"

invoice.paymentMethod.enabled

boolean

invoice.paymentMethod.name

string | null

invoice.paymentMethod.creationDate

string

invoice.paymentMethod.expirationDate

string | null

invoice.paymentMethod.card

object

The card data of the payment method, if the type is "card"

invoice.paymentMethod.sepaDebit

object

The sepa mandate data of the payment method, if the type is "sepa_debit"

invoice.paymentMethod.paypal

object

The paypal data of the payment method, if the type is "paypal"

invoice.type

enum<string>

The type of the invoice.

Available options:

TYPE_INVOICE,

TYPE_CREDIT,

TYPE_REFUND,

TYPE_REMINDER,

TYPE_CANCEL,

TYPE_DUNNING

Example:

"TYPE_INVOICE"

invoice.currencyCode

string

The currency code of the invoice. If multiple currency codes will be used in the positions, they will be converted to that base currency.

Example:

"EUR"

invoice.number

string

The document id of the invoice. This will be generated, when the invoice will be finalized.

Example:

"RE-0000000001"

invoice.status

enum<string>

Available options:

STATUS_DRAFT,

STATUS_PAID,

STATUS_CANCELLED,

STATUS_CLOSED,

STATUS_REFUNDED,

STATUS_REMINDED,

STATUS_UNPAID,

STATUS_NEW,

STATUS_FINALIZING

invoice.finalizationDate

string | null

invoice.dueDate

string | null

invoice.dunningLevel

integer

invoice.dunningStatus

enum<string>

default:none

Available options:

reminder,

dunning,

none

Example:

"none"

invoice.payDate

string | null

invoice.invoiceAddress

any | null

The invoice address of the invoice.

invoice.internalNote

string | null

deprecated

The notice of the invoice.

Example:

"This invoice is with a special discount."

invoice.netAmount

object

The net amount of the invoice.

invoice.grossAmount

object

invoice.taxAmount

object

invoice.customFields

object | null

Example:

{ "field1": "value1", "field2": "value2" }

invoice.unpaidAmount

object

subscription

object | null

The subscription of the cart. If the cart has no recurring items (has only one-time fees), no subscription will be created.

subscription.id

string

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

subscription.externalId

string | null

subscription.number

string

The number of the subscription.

Example:

"S-00000001"

subscription.name

string | null

The name of the subscription. Defaults to the name of the plan. This will be used in the invoice for the grouping headers.

Example:

"Fitness M"

subscription.billingGroup

object | null

The billing group defines the billing cycle of the subscription.

subscription.periods

object[]

subscription.status

any

The status of the subscription.

Possible values:

draft: The subscription is in draft mode and not active yet.
active: The subscription is active and will be billed.
paused: The subscription is paused and will not be billed.
cancelled: The subscription is cancelled and will not be billed anymore.
terminated: The subscription is terminated and will not be billed anymore.
offer: The subscription is an offer and waiting for acceptance.

subscription.activatedAt

string | null

The date the subscription was activated.

Example:

"2021-01-01T00:00:00+00:00"

subscription.poNumber

string | null

The po number of the subscription.

Example:

"PO-00000001"

subscription.contractDetails

object

The contract details of the subscription.

subscription.trialEndsOn

string | null

The date the trial period ends.

Example:

"2021-01-01T00:00:00+00:00"

subscription.customFields

object | null

Example:

{ "field1": "value1", "field2": "value2" }

subscription.nextBillingDate

string | null

The next billing date of the subscription.

subscription.lastBillingAt

string | null

The last billing date of the subscription.

subscription.partner

object | null

The partner of the customer.

metadata

string[]

A collection of key-value pairs that can be linked to an object. This feature is beneficial for storing extra details regarding the object in an organized manner. To remove all keys, simply submit an empty value to the metadata.

Example:

{ "yourKey": "value" }

transactions

object[]

The transactions of the cart.

transactions.id

string

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

transactions.type

enum<string>

default:payment

Available options:

payment,

refund

Example:

"payment"

transactions.status

any

The status of the transaction.

Possible values:

new: The transaction is new and not yet processed. A new transaction is created when a payment is initiated.
authorized: The transaction is authorized and can be captured.
authorizing: The transaction is authorizing. No actions can be performed on the transaction.
waiting: The transaction is waiting for a response from the payment provider, or a customer input. No actions can be performed on the transaction.
offsite_authorization_required: The transaction requires an offsite authorization, e.g. 3D Secure. The customer is informed about the required authorization and redirected to the payment provider.
booked: The transaction is captured and booked on the account.
captured: The transaction is captured and will be booked on the account.
dispute: The transaction is disputed.
manual: Legacy status. Do not use.
canceled: The transaction is canceled, e.g. by the customer during the payment process, or by the merchant.
pending: The transaction is pending, and will be processed soon by the payment provider.
expired: The transaction is expired, e.g. because the customer did not complete the payment process in time.
processing: The transaction is processing, e.g. because the payment provider is currently processing the payment.
failed: The transaction failed, e.g. because the payment provider could not process the payment.
unknown: The transaction status is unknown.
refunded: The transaction is fully refunded.
payedout: The transaction was a payout.
partial_refunded: The transaction is partially refunded.
refund_failed: The transaction refund failed.

transactions.description

string

The description of the transaction.

Example:

"Payment for invoice #123"

transactions.documentNumber

string

The internal reference number of the transaction.

Example:

"123456789"

transactions.currencyCode

object

The currency code of the transaction.

transactions.amount

integer

The original amount which was requested.

Example:

500

transactions.refundedAmount

integer

The amount which was refunded.

transactions.chargedAmount

integer

The amount which was charged to the payment method.

Example:

500

transactions.feeAmount

integer | null

The amount of the transaction fee.

Example:

50

transactions.createdAt

string

The date when the transaction was created.

transactions.paidAt

string | null

The date when the transaction was charged.

Retrieves completed carts of the current tenant.Retrieves a cart by its ID.

curl -X GET \
 /checkout/carts/{id} \
 --header "Authorization: Bearer <token>"

{
  "id": "c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b",
  "status": "<any>",
  "customer": "c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b",
  "customerEmail": {
    "id": "00000000-0000-0000-0000-000000000000",
    "email": "john.doe@example.com",
    "receiverName": "John Doe",
    "type": "TYPE_COMPANY",
    "default": "true"
  },
  "invoiceAddress": {
    "id": "<string>",
    "vatId": "DE123456789",
    "type": "TYPE_DEFAULT",
    "default": "true",
    "status": "active",
    "city": "Berlin",
    "zip": "12345",
    "street": "Musterstraße",
    "houseNumber": "1a",
    "countryCode": "DE",
    "companyName": "ACME Inc.",
    "salutation": "Herr",
    "addition": "c/o John Doe",
    "costCentre": "123456789",
    "firstName": "John",
    "lastName": "Doe"
  },
  "paymentMethod": "c1b0d0c0-0b0b-4b0b-8b0b-0b0b0b0b0b0b",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "redirectUrl": "<string>",
  "items": [
    {
      "id": "<string>",
      "product": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "name": "Basic",
        "description": "For small teams.",
        "type": "product",
        "invoiceVisibility": "always",
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "pricePlan": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "type": "<any>",
        "applyTrial": true,
        "payInAdvance": true,
        "proRata": true,
        "freeUnits": {},
        "billingInterval": "1M",
        "showPricePerInterval": "1M",
        "currencyCode": {},
        "price": {
          "amount": 123,
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00",
          "tenantId": "<string>"
        }
      },
      "quantity": {},
      "type": "product",
      "periods": [
        {
          "id": "<string>",
          "contractPeriodCount": 123,
          "contractPeriod": {},
          "cancellationPeriod": {}
        }
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "customer": {
      "id": "00000000-0000-0000-0000-000000000000",
      "customerNumber": "CUSTOMER-000",
      "timeZone": "Europe/Berlin",
      "firstName": "John",
      "lastName": "Doe",
      "currencyCode": "EUR",
      "companyName": "Acme Inc.",
      "datevId": "123456789",
      "status": "STATUS_ACTIVE"
    },
    "paymentMethod": {
      "id": "<string>",
      "gatewayName": "wallet",
      "type": "sepa_debit",
      "default": true,
      "status": "active",
      "enabled": true,
      "name": "<string>",
      "creationDate": "2023-11-07T05:31:56Z",
      "expirationDate": "2023-11-07T05:31:56Z",
      "card": {
        "brand": "Visa",
        "last4": "4242",
        "expMonth": 12,
        "expYear": 2022,
        "cardHolder": "Max Mustermann"
      },
      "sepaDebit": {
        "iban": "DE8937*********3232",
        "bic": "COBADEFFXXX",
        "mandateReference": "MNDT-2021-123456",
        "signingDate": "2021-01-01T00:00:00+00:00"
      },
      "paypal": {
        "email": "max@mustermann.de",
        "billingAgreementId": "I-1J5gqz2eZvKYlo2C2X2X2X2X"
      }
    },
    "type": "TYPE_INVOICE",
    "currencyCode": "EUR",
    "number": "RE-0000000001",
    "status": "STATUS_DRAFT",
    "finalizationDate": "2023-11-07T05:31:56Z",
    "dueDate": "2023-11-07T05:31:56Z",
    "dunningLevel": 123,
    "dunningStatus": "none",
    "payDate": "2023-11-07T05:31:56Z",
    "invoiceAddress": "<any>",
    "internalNote": "This invoice is with a special discount.",
    "netAmount": {},
    "grossAmount": {},
    "taxAmount": {},
    "customFields": {
      "field1": "value1",
      "field2": "value2"
    },
    "unpaidAmount": {}
  },
  "subscription": {
    "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
    "externalId": "<string>",
    "number": "S-00000001",
    "name": "Fitness M",
    "billingGroup": {},
    "periods": [
      {
        "id": "<string>",
        "contractPeriodCount": 123,
        "contractPeriod": {},
        "cancellationPeriod": {}
      }
    ],
    "status": "<any>",
    "activatedAt": "2021-01-01T00:00:00+00:00",
    "poNumber": "PO-00000001",
    "contractDetails": {
      "contractStart": "2023-11-07T05:31:56Z",
      "contractEnd": "2023-11-07T05:31:56Z"
    },
    "trialEndsOn": "2021-01-01T00:00:00+00:00",
    "customFields": {
      "field1": "value1",
      "field2": "value2"
    },
    "nextBillingDate": "2023-11-07T05:31:56Z",
    "lastBillingAt": "2023-11-07T05:31:56Z",
    "partner": {
      "id": "ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b",
      "name": "John Doe",
      "number": "123456",
      "email": "partner@example.com"
    }
  },
  "metadata": {
    "yourKey": "value"
  },
  "transactions": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "type": "payment",
      "status": "<any>",
      "description": "Payment for invoice #123",
      "documentNumber": "123456789",
      "currencyCode": "EUR",
      "amount": 500,
      "refundedAmount": 123,
      "chargedAmount": 500,
      "feeAmount": 50,
      "createdAt": "2023-11-07T05:31:56Z",
      "paidAt": "2023-11-07T05:31:56Z"
    }
  ]
}

API documentation

User

Tenant

Feature

Entitlement

User & permissions

Settings

Payment

Analytics

Customer

Billing

Dunning

Subscription

Offers

Catalogue

Checkout

Accounting

Taxes

Retrieves a cart by its ID.

Authorizations

Path Parameters

Response