openapi: 3.0.0 info: title: Checkout Backend version: '2.0' description: |- The Checkout Backend API is used to initialize an order through authenticated requests. This includes the ability to create and manipulate orders in Checkout. Refer to the changelog for the latest updates to this API. termsOfService: https://boldcommerce.com/terms-of-service contact: name: Contact Us url: https://developer-dashboard.boldcommerce.com/default/contactus servers: - url: https://api.boldcommerce.com security: - OAuthToken: [] - APIAccessToken: [] tags: - name: Customers description: A child of the Order resource. Contains information about authenticated customers on your store, including name, email, and saved addresses. Use these endpoints to add or remove an authenticated customer to an order. - name: Line Items description: A child of the Order resource. Contains information about the product and the taxes, fees, and discounts associated with it. Use these endpoints to update information about one or multiple line items. - name: Orders description: Contains information about a single order, including the JWT, order ID, and application state. Use these endpoints to initialize, refresh, or cancel an order. - name: Payments description: A child of the Order resource. Contains information about the payments on an order. Use these endpoints to capture partial or full payments. - name: Refunds description: Contains information about any refunds applied to the order. Use these endpoints to apply partial or full refunds. externalDocs: description: For more information about Checkout, refer to the Overview. url: https://developer.boldcommerce.com/guides/checkout paths: /checkout/orders/{shop_identifier}/init: parameters: - $ref: '#/components/parameters/shop_identifier' post: summary: Initialize Order operationId: InitializeOrder tags: - Orders description: |- Initializes an order and retrieves a JWT. You must use the JWT to authorize all requests to the [Checkout Frontend API](checkout). The request body of this endpoint is flexible — you can use dynamic data from the platform to provide information about the cart and customer, or leave it blank and populate the order later. If you initialize an empty order, the [Populate a Checkout Order](/guides/checkout/populate-order) page outlines a suggested flow for adding information to the order after calling this endpoint. **Note:** You must call this endpoint from your backend application. This endpoint returns information that is not safe to share with the frontend application. requestBody: content: application/json: schema: type: object properties: cart_id: $ref: '#/components/schemas/CartID' access_token: $ref: '#/components/schemas/AccessToken' cart_items: description: An array of items to add to the cart. Note that the "Generic Cart Item" type is only supported by BigCommerce, commercetools, and Shopify. type: array items: anyOf: - $ref: '#/components/schemas/GenericCartItem' - $ref: '#/components/schemas/SKUCartItem' - $ref: '#/components/schemas/VariantIDCartItem' customer: $ref: '#/components/schemas/Customer' order_meta_data: $ref: '#/components/schemas/OrderMetaData' resumable_link: $ref: '#/components/schemas/ResumableLink' flow_id: $ref: '#/components/schemas/FlowId' api_session_id: $ref: '#/components/schemas/ApiSessionId' examples: Cart Token: $ref: '#/components/examples/cart_token' Generic Cart: $ref: '#/components/examples/generic_cart' Gift Card Cart: $ref: '#/components/examples/gift_card_cart' SKU Cart: $ref: '#/components/examples/sku_cart' Variant ID Cart: $ref: '#/components/examples/variant_id_cart' Authenticated Customer: $ref: '#/components/examples/authenticated_customer' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: initial_data: $ref: '#/components/schemas/InitialData' application_state: $ref: '#/components/schemas/ApplicationState' jwt_token: $ref: '#/components/schemas/JWTToken' public_order_id: $ref: '#/components/schemas/PublicOrderId' cart_customer_id: type: string nullable: true description: |- The platform ID of an authenticated customer. This value is populated only if you provide a `cart_id` in the Initialize Order request and the customer who created the cart is logged in. Note: This property does not associate the customer with the order. You must still add the customer to the order using the [Create Authenticated Customer](orders#operation/CreateAuthenticatedCustomer) endpoint. example: '100000009' /checkout/orders/{shop_identifier}/resume: parameters: - $ref: '#/components/parameters/shop_identifier' post: summary: Resume Order operationId: ResumeOrder tags: - Orders description: |- Use this endpoint to resume an existing order, such as one that was previously abandoned. You can also use this endpoint can also be used to generate a new JWT for an order. Each JWT expires after 60 minutes. requestBody: content: application/json: schema: properties: public_order_id: $ref: '#/components/schemas/PublicOrderId' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: jwt_token: $ref: '#/components/schemas/JWTToken' initial_data: $ref: '#/components/schemas/InitialData' application_state: $ref: '#/components/schemas/ApplicationState' public_order_id: $ref: '#/components/schemas/PublicOrderId' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Error' examples: example-1: value: message: The public order id field is required. type: authorization field: public_order_id severity: validation sub_type: '' /checkout/orders/{shop_identifier}/create: parameters: - $ref: '#/components/parameters/shop_identifier' post: summary: Create Order operationId: CreateOrder tags: - Orders description: |- Use this endpoint to create and process a full order without additional API interaction. You can also use this endpoint to create a portion of an order, to be completed at a later time. For more information about using this endpoint, refer to [Programmatically Create an Order](/guides/checkout/create-order). requestBody: content: application/json: schema: type: object properties: idempotency_key: type: string description: A unique identifier for this transaction. If the API receives multiple requests with the same key, it always picks up where it left off, and no duplicate orders are created. cart_id: $ref: '#/components/schemas/CartID' access_token: $ref: '#/components/schemas/AccessToken' cart_items: description: Array of items to add to the cart. If using in conjunction with `cart_id`, these items will be added to the existing cart alongside existing items in the cart. type: array items: allOf: - anyOf: - $ref: '#/components/schemas/GenericCartItem' - $ref: '#/components/schemas/SKUCartItem' - $ref: '#/components/schemas/VariantIDCartItem' - type: object properties: fees: type: array minItems: 0 items: type: object properties: description: type: string description: A human-readable description of the fee that can be displayed in a user interface. type: type: string enum: - fixed - percentage description: The type of the fee applied to the line item. value: type: integer description: | The fee amount to apply to the line item. * For `"fixed"` fees, represent the value in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. * For `"percentage"` fees, represent the value as a percentage of the line item amount between 0 and 100. taxable: type: boolean description: Indicates whether to include the fee should be included in the line item total when calculating taxes. taxes: type: array description: Pre-calculated taxes to be applied to the line item fee. minItems: 0 items: $ref: '#/components/schemas/Tax' required: - description - type - value taxes: type: array description: Pre-calculated taxes to be applied to the line item. minItems: 0 items: $ref: '#/components/schemas/Tax' customer: $ref: '#/components/schemas/Customer' shipping_address: $ref: '#/components/schemas/Address' billing_address: $ref: '#/components/schemas/Address' shipping_line: type: object description: The order's shipping information. properties: rate_name: type: string description: A human-readable description of the shipping line that can be displayed in a user interface. cost: type: number minimum: 0 description: Cost of the shipping line in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. taxes: type: array minItems: 0 description: Pre-calculated taxes to be applied to the shipping cost. items: $ref: '#/components/schemas/Tax' required: - rate_name - cost discounts: $ref: '#/components/schemas/Discounts' fees: type: array description: The fees applied to order. Note that order-level fees are only supported by Shopify and custom platforms. items: type: object properties: id: type: string description: A unique identifier to the fee. description: type: string description: A human-readable description of the fee that can be displayed in a user interface. type: type: string enum: - fixed - percentage description: The type of the fee applied to the order. value: type: integer description: | The fee amount to apply to the order. * For `"fixed"` fees, represent the value in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. * For `"percentage"` fees, represent the value as a percentage of the order subtotal between 0 and 100. required: - id - description - type - value payments: type: array description: An array of payments to apply to the order. Bold first processes payments with amounts, followed by those without amounts. Within these groups, payments are applied in the order they are received, and Bold stops processing payments when the order total is reached. items: allOf: - anyOf: - title: Customer default payment method type: object properties: public_customer_id: type: string description: Public identifier of the customer. The customer's default payment method is used for payment. required: - public_customer_id - title: Payment method type: object properties: public_payment_method_id: type: string description: Public identifier of the payment method. required: - public_payment_method_id - type: object properties: amount: type: number description: Amount to charge on a particular payment, up to the order total, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. Defaults to order total. currency: type: string description: Currency code for the order, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. If none is given, the store default will be used. order_meta_data: $ref: '#/components/schemas/OrderMetaData' commands: type: object description: A list of commands for Bold Checkout to perform on the created order, with integer keys. Bold executes these commands in sorted order based on keys. additionalProperties: type: string enum: - calculate_shipping - calculate_tax_rates - authorize_payments - process_order - send_to_platform - charge_payments flow_id: $ref: '#/components/schemas/FlowId' api_session_id: $ref: '#/components/schemas/ApiSessionId' required: - idempotency_key examples: Create and Process Order using Bold Checkout Calculations and Item SKUs: value: cart_items: - sku: KLS_472945 quantity: 2 line_item_key: db3b1963-6ddd-4115-9f45-64c7edb3867d line_item_properties: colour: red size: small customer: first_name: Robert last_name: Walsh email_address: rwalsh24@example.com accepts_marketing: false public_id: 6xID7o9hrxQ7bkVIKvCxXPD7Cf3P4BP141wplqPTa3CYYwEqM5X9w7JzKWulQe4p shipping_address: first_name: Robert last_name: Walsh address_line_1: 2652 John Daniel Drive city: Dexter province: Missouri province_code: MO country: United States of America country_code: US postal_code: '63841' billing_address: first_name: Robert last_name: Walsh address_line_1: 2652 John Daniel Drive city: Dexter province: Missouri province_code: MO country: United States of America country_code: US postal_code: '63841' discounts: - discount_code: SPRINGSALE2022_Q8RT4 payments: - public_payment_method_id: ftziZRlloXJhR8emShyZePgaZxFTp9TN6Ai0tVWOB223g9qCGQQFA27ccW2fx72U currency: USD idempotency_key: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 commands: '0': calculate_shipping '1': calculate_tax_rates '2': authorize_payments '3': process_order '4': send_to_platform '5': charge_payments Create and Process Order with Precalculated Taxes, Fees, and Shipping: value: cart_items: - id: 9563957 quantity: 1 title: AAA Batteries, 12-pack weight: 200 requires_shipping: true price: 1657 line_item_key: eebfc1ec-7736-4180-9d8d-28f4a5fcd841 line_item_properties: colour: red size: small fees: - description: Eco-fee type: fixed value: 24 taxes: - name: GST rate: 5 - name: PST rate: 7 taxes: - name: GST rate: 5 - name: PST rate: 7 customer: first_name: Alicia last_name: Hobbes email_address: alicia.hobbes@example.com accepts_marketing: false public_id: t8xFvAFG4cAuv3MxsTR66QFKBdOM3dxYJxvDd9EmjVBZJ0opN8Jomg0VEA3zUltc shipping_address: first_name: Alicia last_name: Hobbes address_line_1: 4139 Nelson Street city: Ottawa province: Ontario province_code: 'ON' country: Canada country_code: CA postal_code: K1N7W4 billing_address: first_name: Alicia last_name: Hobbes address_line_1: 2070 Bank Street address_line_2: PO Box 153 city: Ottawa province: Ontario province_code: 'ON' country: Canada country_code: CA postal_code: K2P2N2 shipping_line: rate_name: Express Ground cost: 2550 taxes: - name: GST rate: 5 - name: PST rate: 7 discounts: - discount_code: TENPERCENTOFF fees: - id: VEA3zUltc description: Order-fee type: fixed value: 24 payments: - public_payment_method_id: ftziZRlloXJhR8emShyZePgaZxFTp9TN6Ai0tVWOB223g9qCGQQFA27ccW2fx72U currency: CAD idempotency_key: 36f6c1c1-9e93-4eb9-be06-bcfee5fd7b44 commands: '0': authorize_payments '1': process_order '2': send_to_platform '3': charge_payments Create draft order with Platform Variant IDs: value: cart_items: - platform_id: 993746 quantity: 1 line_item_key: 10f0be4b-9ffb-4a75-bfe2-6486a0abd793 line_item_properties: colour: red size: small customer: email_address: shopaholic135@example.com shipping_address: first_name: Charles last_name: Barker address_line_1: 1 Water Street city: Redwood Meadows province: Alberta province_code: AB country: Canada country_code: CA postal_code: T3Z3J2 billing_address: first_name: Charles last_name: Barker address_line_1: 1 Water Street city: Redwood Meadows province: Alberta province_code: AB country: Canada country_code: CA postal_code: T3Z3J2 idempotency_key: ef0cd190-c439-4eb7-9e6d-8d5b4090302e responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: application_state: $ref: '#/components/schemas/ApplicationState' public_order_id: type: string example: o10KL4Crlb8Lh4zg4t5kImS6CFvdFI1t5Aybxlor1B52GDGAZvn6X85wy6oDfWZP '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array minItems: 0 items: $ref: '#/components/schemas/ErrorV2' /checkout/orders/{shop_identifier}/{public_order_id}/customer: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' delete: summary: Delete Customer operationId: DeleteCustomer tags: - Customers description: Deletes the customer from the order. responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: application_state: $ref: '#/components/schemas/ApplicationState' examples: Deleted Customer: $ref: '#/components/examples/NoCustomer' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: example-1: value: message: The public_order_id field is required. type: order field: public_order_id severity: validation sub_type: customer /checkout/orders/{shop_identifier}/{public_order_id}/customer/authenticated: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' post: summary: Create Authenticated Customer operationId: CreateAuthenticatedCustomer tags: - Customers description: |- Creates a new authenticated customer. You cannot create a customer when a customer already exists on the order. If you wish to add a new authenticated customer to an order, you must first delete the existing customer using the [Delete Customer](checkout#operation/DeleteCustomer) endpoint. requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthenticatedCustomerBody' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: customer: $ref: '#/components/schemas/Customer' application_state: $ref: '#/components/schemas/ApplicationState' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: example-1: value: message: The email address field is required. type: order field: email_address severity: validation sub_type: customer /checkout/orders/{shop_identifier}/{public_order_id}/cancel: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' post: summary: Cancel Order operationId: CancelOrder tags: - Orders description: Cancels an order, voiding any held authorizations. This endpoint fails if the order is already fulfilled or any payments were captured. requestBody: content: application/json: schema: type: object properties: reason: description: An optional order cancellation reason. type: string example: Duplicate order. responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: application_state: $ref: '#/components/schemas/ApplicationState' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: Payment already captured: value: code: 02-92 type: order.order_in_non_cancellable_state message: Cannot cancel order with captured payments. Order already fulfilled: value: code: 02-92 type: order.order_in_non_cancellable_state message: Cannot cancel order, already fulfilled. /checkout/orders/{shop_identifier}/{public_order_id}/payments/capture: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' post: summary: Capture Payment for Arbitrary Amount operationId: CapturePaymentForArbitraryAmount description: Captures a payment for the amount specified against the order total (shipping, taxes, etc., included). tags: - Payments responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CapturePaymentResponse' example: data: order_total: 1200 amount_remaining: 600 paid_total: 600 captured_held_total: 0 transactions: - gateway: Stripe Default Name gateway_id: bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi amount: 600 transaction_id: ch_1GvDW4JhIKSKpq8w9SoshRef reference_transaction_id: null response_code: '' status: success '202': description: Order has been accepted but payments are held for capture by the payment gateway. Will complete processing order once payment gateway has captured the payment. x-summary: Order Accepted, Payment Held By Gateway content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: HeldForReview: value: code: 02-21 type: checkout.order_charge_failed message: Payment held for review for order 1444 details: {} '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: NotEnoughFunds: value: code: 02-50 type: checkout.api_validation_failed message: Not enough funds left to capture requested amount details: order_total: 2500 total_paid: 1121 amount_left_to_capture: 1379 attempted_capture_amount: 500000 NoAuthorizeTransaction: value: code: 02-44 type: checkout.api_payment_capture_failed message: No authorize transaction found to capture details: order_total: 2500 total_paid: 2000 amount_remaining: 500 TransactionFailed: value: code: 02-44 type: checkout.api_payment_capture_failed message: API token mismatch:{"code":0,"error":"processor_declined","field":"cc_number","message":"API token mismatch","service":"credit_card.moneris","severity":"critical","side":"cashier","type":"payment_gateway","details":""} details: order_total: 2500 total_paid: 500 amount_remaining: 2000 gateway: Moneris attempted_capture_amount: 500 reference_transaction_id: '' requestBody: content: application/json: schema: $ref: '#/components/schemas/CapturePartialPaymentRequest' examples: FullAmountProvided: value: amount: 1200 reauth: true idempotent_key: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 capture_data: data: external_id: legacy-id-135798642 PartialAmountProvided: value: amount: 600 reauth: true idempotent_key: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 capture_data: data: external_id: legacy-id-135798642 /checkout/orders/{shop_identifier}/{public_order_id}/payments/sale/{payment_id}: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' - $ref: '#/components/parameters/payment_id' post: summary: Capture Specific Payment operationId: CaptureSpecificPayment description: |- Manually authorizes and charges the amount specified to a payment on the order. The payment must have an `awaitingPreAuth` status. The payment is applied against the order total (including shipping, taxes, etc.). This endpoint enables you to delay the payment capture process. Normally, Bold Checkout adds payments to the order with a `preAuthed` status, indicating they have already been authorized for the given amount. When Bold is set up to only verify the payments, each payment is added to the order with a `awaitingPreAuth` status. >> **Notes:** >> - Reach out to the [Support Team](https://support.boldcommerce.com/hc/en-us/requests/new?ticket_form_id=1900000280347) with a request to enable "only verify payments" functionality. >> - Supported for Braintree and [External Payment Gateways](/guides/checkout/checkout-epg-guide) only. tags: - Payments responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CapturePaymentResponse' example: data: order_total: 1200 amount_remaining: 600 paid_total: 600 captured_held_total: 0 transactions: - gateway: Stripe Default Name gateway_id: bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi amount: 600 transaction_id: ch_1GvDW4JhIKSKpq8w9SoshRef reference_transaction_id: null response_code: '' status: success '202': description: The order was accepted, but payments are held for capture by the payment gateway. Bold completes processing the order once the payment gateway captures the payment. x-summary: Order Accepted, Payment Held By Gateway content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: HeldForReview: value: code: 02-21 type: checkout.order_charge_failed message: Payment held for review for order 1444 details: {} '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: NotEnoughFunds: value: code: 02-50 type: checkout.api_validation_failed message: Not enough funds left to capture requested amount details: order_total: 2500 total_paid: 1121 amount_left_to_capture: 1379 attempted_capture_amount: 500000 NoAuthorizeTransaction: value: code: 02-44 type: checkout.api_payment_capture_failed message: No authorize transaction found to capture details: order_total: 2500 total_paid: 2000 amount_remaining: 500 TransactionFailed: value: code: 02-44 type: checkout.api_payment_capture_failed message: API token mismatch:{"code":0,"error":"processor_declined","field":"cc_number","message":"API token mismatch","service":"credit_card.moneris","severity":"critical","side":"cashier","type":"payment_gateway","details":""} details: order_total: 2500 total_paid: 500 amount_remaining: 2000 gateway: Moneris attempted_capture_amount: 500 reference_transaction_id: '' requestBody: content: application/json: schema: $ref: '#/components/schemas/CapturePartialPaymentRequest' examples: FullAmountProvided: value: amount: 1200 reauth: true idempotent_key: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 capture_data: data: external_id: legacy-id-135798642 PartialAmountProvided: value: amount: 600 reauth: true idempotent_key: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 capture_data: data: external_id: legacy-id-135798642 /checkout/orders/{shop_identifier}/{public_order_id}/payments/capture/full: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' post: summary: Capture Payment for Full Order Amount operationId: CapturePaymentForFullOrderAmount tags: - Payments description: Captures a payment for the full order total amount (including shipping, taxes, etc). responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CapturePaymentResponse' example: data: order_total: 1200 amount_remaining: 600 paid_total: 600 captured_held_total: 0 transactions: - gateway: Stripe Default Name gateway_id: bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi amount: 600 transaction_id: ch_1GvDW4JhIKSKpq8w9SoshRef reference_transaction_id: null response_code: '' status: success '202': description: The Order has been accepted, but the payment gateway is holding the payments for capture. The request will complete when the payment gateway captures the payments. x-summary: Order Accepted, Payment Held By Gateway content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: HeldForReview: value: code: 02-21 type: checkout.order_charge_failed message: Payment held for review for order 1444 details: {} '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: NotEnoughFunds: value: code: 02-50 type: checkout.api_validation_failed message: No funds left to capture on this order details: order_total: 2500 total_paid: 2500 amount_left_to_capture: 0 NoAuthorizeTransaction: value: code: 02-44 type: checkout.api_payment_capture_failed message: No authorize transaction found to capture details: order_total: 2500 total_paid: 0 amount_remaining: 2500 TransactionFailed: value: code: 02-44 type: checkout.api_payment_capture_failed message: API token mismatch:{"code":0,"error":"processor_declined","field":"cc_number","message":"API token mismatch","service":"credit_card.moneris","severity":"critical","side":"cashier","type":"payment_gateway","details":""} details: order_total: 2500 total_paid: 0 amount_remaining: 2500 gateway: Moneris attempted_capture_amount: 2500 reference_transaction_id: '' requestBody: content: application/json: schema: $ref: '#/components/schemas/CapturePaymentRequest' examples: AmountProvided: value: reauth: true idempotent_key: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 capture_data: data: external_id: legacy-id-135798642 /checkout/orders/{shop_identifier}/{public_order_id}/refunds: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' post: summary: Issue Refund for Arbitrary Amount operationId: IssueRefundForArbitraryAmount tags: - Refunds description: |- Issues a refund for the amount specified against any captured transactions on the order. Notifies the connected stock inventory service to restock the returned line items (if applicable). This endpoint does not perform any currency conversions. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RefundResponse' examples: ExamplePartialRefund: value: data: amount_refunded: 6055 transaction_details: - success: true amount: 6055 transaction_number: ch_1GvDW4JhIKSKpq8w9SoshRef created_at: '2021-01-15 01:01:01' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: FailedPaymentGatewayAttempts: value: code: 02-28 type: checkout.order_refund_failed message: Attempted to refund 2 transactions on payment gateway but none succeeded. details: {} FailedToPushToPlatform: value: code: 02-41 type: checkout.api_sending_order_to_platform_failed message: Full refund was successful but couldn't push to platform. details: {} application/xml: schema: type: object properties: {} requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundRequest' examples: BrokenProduct: value: amount: 6055 reason: Product arrived broken. email_notification: true refund_meta_data: data: external_id: legacy-id-135798642 /checkout/orders/{shop_identifier}/{public_order_id}/refunds/{payment_id}: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' - $ref: '#/components/parameters/payment_id' post: summary: Refund a Specific Payment for an Arbitrary Amount operationId: IssuePaymentRefundForArbitraryAmount tags: - Refunds description: |- Issues a refund for the amount specified against a specific transactions on the order, identified by `payment_id`. Notifies the connected stock inventory service to restock the returned line items (if applicable). This endpoint does not perform any currency conversions. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RefundResponse' examples: ExamplePartialRefund: value: data: amount_refunded: 6055 transaction_details: - success: true amount: 6055 transaction_number: ch_1GvDW4JhIKSKpq8w9SoshRef created_at: '2021-01-15 01:01:01' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: FailedPaymentGatewayAttempts: value: code: 02-28 type: checkout.order_refund_failed message: Attempted to refund 2 transactions on payment gateway but none succeeded. details: {} FailedToPushToPlatform: value: code: 02-41 type: checkout.api_sending_order_to_platform_failed message: Full refund was successful but couldn't push to platform. details: {} application/xml: schema: type: object properties: {} requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundRequest' examples: BrokenProduct: value: amount: 6055 reason: Product arrived broken. email_notification: true refund_meta_data: data: external_id: legacy-id-135798642 /checkout/orders/{shop_identifier}/{public_order_id}/refunds/full: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' post: summary: Issue Refund for Full Order Amount operationId: IssueRefundForFullOrderAmount tags: - Refunds description: |- Issues a refund for the entire order (including shipping, taxes, etc). Restocks line items (if applicable). This endpoint does not perform any currency conversions. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RefundResponse' examples: ExampleFullRefund: value: data: amount_refunded: 6055 transaction_details: - success: true amount: 6055 transaction_number: ch_1GvDW4JhIKSKpq8w9SoshRef created_at: '2021-01-15 01:01:01' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: FailedPaymentGatewayAttempts: value: code: 02-28 type: order_refund_failed message: Attempted to refund 2 transactions on payment gateway but none succeeded. details: {} FailedToPushToPlatform: value: code: 02-41 type: api_sending_order_to_platform_failed message: Full refund was successful but couldn't push to platform. details: {} requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundRequestFull' examples: BrokenProduct: value: reason: Product arrived broken. email_notification: true refund_meta_data: data: external_id: legacy-id-135798642 /checkout/orders/{shop_identifier}/{public_order_id}/line_items/{line_item_key}: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' - schema: $ref: '#/components/schemas/LineItemKey' name: line_item_key in: path required: true patch: summary: Update Line Item operationId: UpdateLineItem tags: - Line Items description: |- Updates the `fulfilled_quantity` property of a single line item. For more information, refer to the [Fulfill an Order guide](/guides/checkout/fulfill-order). responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: line_item: $ref: '#/components/schemas/LineItem' application_state: $ref: '#/components/schemas/ApplicationState' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: LineItemKeyMissing: value: code: 11-13 type: line_items message: The line item key field is required. details: null requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchLineItem' /checkout/orders/{shop_identifier}/{public_order_id}/line_items: parameters: - $ref: '#/components/parameters/shop_identifier' - $ref: '#/components/parameters/public_order_id' patch: summary: Update Line Items operationId: UpdateLineItems tags: - Line Items description: |- Updates the `fulfilled_quantity` property of multiple line items. For more information, refer to the [Fulfill an Order guide](/guides/checkout/fulfill-order). responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: line_items: type: array items: $ref: '#/components/schemas/LineItem' application_state: $ref: '#/components/schemas/ApplicationState' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: LineItemKeyMissing: value: code: 11-13 type: line_items message: The line item key field is required. details: null requestBody: content: application/json: schema: type: object properties: line_items: type: array items: allOf: - type: object properties: line_item_key: $ref: '#/components/schemas/LineItemKey' required: - line_item_key - $ref: '#/components/schemas/PatchLineItem' examples: Set fulfilled quantity of multiple items: value: line_items: - fulfilled_quantity: 1 line_item_key: oak_cheese_grater_2643 - fulfilled_quantity: 3 line_item_key: oak_cheese_grater_3000 components: securitySchemes: OAuthToken: type: oauth2 flows: authorizationCode: authorizationUrl: https://apps.boldapps.net/accounts/dashboard/authorize tokenUrl: https://api.boldcommerce.com/auth/oauth2/token scopes: {} description: Authenticates an API request from a [public integration](/guides/getting-started/glossary#public-integration). Generate this token in the [Developer Dashboard](https://developer-dashboard.boldcommerce.com/default/dashboard). Refer to [Build Public Integrations](/default/guides/getting-started/public-integrations) for more information. APIAccessToken: type: apiKey name: API Access Token in: header description: Authenticates an API request from a [private integration](/guides/getting-started/glossary#private-integration). Generate this token in the [Bold Account Center](https://account.boldcommerce.com/). Refer to the [Quick Start](/guides/getting-started/quick-start) for more information. parameters: shop_identifier: schema: type: string example: zp3oafdor9 name: shop_identifier in: path required: true description: The identifier of the shop, which can be retrieved by making a request to the [Get Info](shops#operation/GetShopInfo) endpoint. public_order_id: schema: type: string example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB name: public_order_id in: path required: true description: The public order id generated when the order is initialized by making a request to the [Initialize Order](orders#operation/InitializeOrder) endpoint. payment_id: schema: type: string example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB name: payment_id in: path required: true description: The identifier assigned to each unique payment. schemas: AuthenticatedCustomerBody: title: Authenticated Customer Body type: object description: The request payload to create a new authenticated customer. properties: platform_id: type: string description: The platform identifier for an authenticated customer. For guest customers, the value for this property will be null. nullable: true example: '50942578465125' public_id: type: string description: The public identifier generated by Checkout for a customer. nullable: true example: pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA first_name: type: string description: The customer's first name. example: John last_name: type: string description: The customer's last name. example: Doe email_address: type: string description: The customer's email address. example: john.doe@example.com accepts_marketing: type: boolean description: If the customer would like to receive any sort of marketing emails. Defaults to `false`. default: false example: false required: - email_address - platform_id SKUCartItem: title: SKU Cart Item type: object description: Cart item based of the product SKU. Product data must be synced with Bold Checkout to work. properties: sku: type: string quantity: type: integer line_item_key: $ref: '#/components/schemas/LineItemKey' line_item_properties: $ref: '#/components/schemas/LineItemProperty' required: - sku - quantity - line_item_key VariantIDCartItem: title: Variant ID Cart Item type: object description: A cart item based off a platform product model. The identifier is unique to the particular platform. For Shopify, it is a variant ID. properties: platform_id: description: The ID of a product variant. type: string example: '1235235' quantity: type: integer description: The quantity of the item in the cart. example: 2 line_item_key: $ref: '#/components/schemas/LineItemKey' line_item_properties: $ref: '#/components/schemas/LineItemProperty' required: - platform_id - quantity - line_item_key AccessToken: type: string description: An optional string token that you can pass to the platform. For example, use this field if your platform requires an authentication token to retrieve cart information (commercetools). example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c CartID: type: string description: Identifier of an existing cart to load from the platform. This field is unsupported when using a custom platform. example: 1snVSJAWYWWYhfLWq9ABcXMwx8mcvh2U GenericCartItem: title: Generic Cart Item type: object description: An array of items to add to the cart. Generic cart items are items that are not created in the platform, and the product data is added to the order by Bold. Generic cart items are supported on BigCommerce, commercetools, and Shopify stores only. properties: quantity: type: integer description: The quantity of the cart item. example: 1 title: type: string description: The item title to display. example: Oak Cheese Grater weight: type: integer description: Weight of the item in grams. example: 1000 taxable: type: boolean description: Indicates whether the item is taxable. example: true image: type: string description: Link to the image to display during checkout. example: http://shop.images/oakcheesegrater requires_shipping: type: boolean description: Indicates whether the item requires shipping. example: true price: description: The item price, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. type: number example: 2350 line_item_key: $ref: '#/components/schemas/LineItemKey' line_item_properties: $ref: '#/components/schemas/LineItemProperty' required: - quantity - title - weight - requires_shipping - price - line_item_key LineItemKey: title: LineItemKey type: string description: A merchant-defined, unique identifier serving to refer to this line throughout Bold Checkout. example: oak_cheese_grater_2643 LineItemProperty: title: Line Item Property type: object description: Any arbitrary property that you want to associate with this item. Line items can also be gift cards, which have specific and unique properties. See the "Gift card properties" example in `line_items` arrays. anyOf: - type: object title: Additional Properties additionalProperties: type: string example: colour: red size: small - $ref: '#/components/schemas/GiftCardProperties' - type: object title: No properties description: Empty object GiftCardProperties: title: Gift Card Properties type: object properties: recipient_name: type: string description: Name of the person the gift card is being sent to. example: John Doe recipient_email: type: string description: Email address the gift card is being sent to. example: johndoe@boldcommerce.com message: type: string description: Personalized message field the buyer can attach to the gift card. Value is `""` if created from an order. example: Dear John, Happy Birthday! custom_amount: type: string description: If included, the price of this particular line item in the checkout order will be overwritten by this value. It is written in base units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: '2450' LineItem: title: Line Item type: object properties: id: type: string description: An internal-only string that Bold uses to identify line items. example: 724bca product_title: type: string description: The name of the product. example: Oak Cheese Grater title: type: string description: The name of the product variant. example: Small image_url: type: string description: The URL for the image of the variant that is displayed on the storefront. example: http://shop.images/oakcheesegrater properties: description: Any additional properties of the line item. Line Items can also be Gift Cards, which have specific and unique properties. See the "Gift card properties" example in `line_items` arrays. anyOf: - type: object title: Additional Properties additionalProperties: type: string - $ref: '#/components/schemas/GiftCardProperties' - type: array title: No properties maxItems: 0 description: type: string description: A description of the product. example: A handmade oak cheese grater to elevate your cheese-eating experience. quantity: type: integer description: The quantity of the line item on the order. example: 2 price: type: number description: The price of one unit of the line item, using cents/base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 2350 total_price: type: number description: The total price of all units of the line item, presented in cents/base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 4700 visible: type: integer description: Indicates whether the item is visible on the storefront. Hard-coded to `1` to indicate `true`. example: 1 line_item_key: $ref: '#/components/schemas/LineItemKey' barcode: type: string description: The barcode for the line item. example: 1234ABC compare_at_price: type: number description: An optional price displayed on the product page to indicate the discount taken. nullable: true example: 4000 weight: type: integer description: The weight of one unit of the line item, measured in `weight_unit`. example: 1000 weight_unit: type: string description: The unit in which to measure the line item weight. example: g product_id: type: string description: A platform-defined identifier for the product on this line item. example: oak-cheese-grater variant_id: oneOf: - type: string - type: number description: A platform-defined identifier for the product variant on this line item. example: oak-cheese-grater-small requires_shipping: type: boolean description: Indicates whether the item must be shipped. example: true sku: type: string description: A merchant-defined stock-keeping unit of the line item. example: OAK_GRATER_SM taxable: type: boolean description: Indicates whether the line item is taxable. example: true tags: type: string description: Any tags attached to the line item. example: Kitchen, Cheese Board, Oak vendor: type: string description: The vendor that supplied the line item. example: Cheese Boards Unlimited total_weight: type: integer description: The total weight of all units of this line item. example: 2000 localized_names: description: | Any localized names for the product. Languages and localized names are configured in the platform. For each configured language, the object contains a property with a key equal to the language (in [ISO 369](https://www.iso.org/iso-639-language-codes.html) format) and value equal to the product name in that language. anyOf: - type: object title: Additional Properties additionalProperties: type: string properties: text: type: string example: fr: Gratteur à fromage en chêne ge: Käsereibe aus Eichenholz - type: array title: No localized_names maxItems: 0 localized_descriptions: description: | Any localized descriptions for the product. Languages and localized descriptions are configured in the platform. For each configured language, the object contains a property with a key equal to the language (in [ISO 369](https://www.iso.org/iso-639-language-codes.html) format) and value equal to the product description in that language. anyOf: - type: object title: Additional Properties additionalProperties: type: string properties: text: type: string example: fr: Un gratteur à fromage en chêne faite à la main pour rehausser votre expérience de dégustation de fromage ge: Eine handgefertigte Käsereibe aus Eichenholz, um Ihr Käseerlebnis zu verbessern - type: array title: No localized_descriptions maxItems: 0 localized_variant_names: description: | Any localized names for the product variant. Languages and localized names are configured in the platform. For each configured language, the object contains a property with a key equal to the language (in [ISO 369](https://www.iso.org/iso-639-language-codes.html) format) and value equal to the product variant name in that language. anyOf: - type: object title: Additional Properties additionalProperties: type: string properties: text: type: string example: fr: Gratteur à fromage en chêne ge: Käsereibe aus Eichenholz - type: array title: No localized_variant_names maxItems: 0 Discount: title: Discount type: object description: A discount, which can be applied either to an individual line item or the order as a whole. properties: code: type: string description: The user-facing discount code name. example: SUMMER5 text: type: string description: A description of the discount, which is displayed on the platform. example: Summer discount code value: type: number example: 500 description: The value of the discount applied, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. source: type: string description: |- The source of the discount code. Possible values are: - `"cart"` discount created from plugin actions [DISCOUNT_CART](/guides/checkout/references/plugin-actions#discount_cart) and/or [DISCOUNT_LINE_ITEMS](/guides/checkout/references/plugin-actions#discount_line_items) - `"coupon"` discount created in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4). example: coupon Discounts: type: array minItems: 0 description: The order's discount information. items: oneOf: - type: object title: Existing Discount Code properties: discount_code: type: string description: Existing discount code to be applied to order. required: - discount_code - type: object title: New Discount properties: type: type: string enum: - fixed - percent - shipping_fixed - shipping_percent - free_shipping description: | Type of discount: * `"fixed"` - Fixed amount to discount from the order total, in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. * `"percent"` - Percent to discount from the order total. * `"shipping_fixed"` - Fixed amount to discount from the shipping total in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. * `"shipping_percent"` - Percent to discount from the shipping total. * `"free_shipping"` - Discounts the full amount of the shipping total. value: type: number minimum: 0 description: | Discount value, described in one of the following ways: * For `"fixed"` and `"shipping_fixed"` type, provide the amount in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. * For `"percent"` and `"shipping_percent"` type, provide the amount as a percentage, between 0 and 100. * For `"free_shipping"` type, leave the value blank. line_text: type: string description: A human-readable description of the discount that can be displayed in a user interface. required: - type - value - line_text OrderMetaData: title: Order Metadata type: object description: Additional information about an order. Metadata can be used as data proxy that Checkout will act upon. It can also be used to include extra information about an order and included when pushed to the platform. properties: cart_parameters: description: Extra information about an order that Checkout can act upon. oneOf: - type: object title: Cart parameters properties: key: type: string example: cp-key1 additionalProperties: type: string example: A cart param. - type: array title: No cart parameters maxItems: 0 note_attributes: description: Extra information added to the order and pushed to the platform. oneOf: - type: object title: Note attributes properties: key: type: string example: na-key1 additionalProperties: type: string example: A note attribute. - type: array title: No note attributes maxItems: 0 notes: type: string description: Notes that can be attached to the order. example: A special delivery note. tags: type: array description: Tags attached to the order. items: type: string example: order-1 LineItemFee: title: Fee type: object description: An additional fee to be added to the line item. properties: amount: type: number description: The fee amount, represented in cents/base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 500 name: type: string description: A description of the fee. example: Miscellaneous fee. GeneralFee: title: GeneralFee type: object properties: id: type: string description: A unique identifier for this fee, used in the [`remove_fee`](/guides/checkout/references/plugin-actions#remove_fee) plugin action. example: '123456789' line_text: type: string description: A user-defined identifier serving to be displayed in any user interfaces. example: Custom Fee — Added by Plugin fee_type: type: string description: The type of the fee, "fixed" or "percentage". example: fixed value: type: integer description: The fee amount, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 10 source: type: string description: The method in which the fee was added to the order, typically through the `add_fee` plugin action. example: PLUGIN plugin_uuid: type: string description: The identifier of the plugin which added the fee to the order. This field is omitted if the fee source was not a plugin. example: a52589f8-09df-11ed-b30e-f67072e164ee taxable: type: boolean description: Indicates whether the fee should be included in the calculation of taxes. example: true show_description: type: boolean description: Indicates whether to show the fee description. Always set to `true` for fees added by plugin. example: true Currency: type: object description: The currency that the order was completed in. properties: iso_code: type: string description: The currency code, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: CAD iso_numeric_code: type: integer description: The numeric currency code, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 124 symbol: type: string description: The symbol associated with the currency. example: $ format: type: string description: The format of the currency, including the symbol and the amount. example: ${{amount}} has_decimal: type: boolean description: Indicates whether the currency uses a decimal. example: true show_iso_code: type: boolean description: Indicates whether to show the ISO code alongside the order total on the storefront. example: true DisplayCurrency: type: object description: The currency that the order was displayed to the user. properties: iso_code: type: string description: The currency code, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: USD iso_numeric_code: type: integer description: The numeric currency code, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 840 symbol: type: string description: The symbol associated with the currency. example: $ format: type: string description: The format of the currency, including the symbol and the amount. example: ${{amount}} has_decimal: type: boolean description: Indicates whether the currency uses a decimal. example: true show_iso_code: type: boolean description: Indicates whether to show the ISO code alongside the order total on the storefront. example: true DisplayExchangeRate: type: number description: The rate of exchange between the currency on the order and the display currency. example: 1.357251 PatchLineItem: title: Line Item Patch type: object x-tags: - app_state properties: fulfilled_quantity: type: integer description: The fulfilled quantity of a line item in an order. example: 2 InitialData: title: Initial Data type: object properties: shop_name: type: string description: The URL of the store. example: examplestore.com country_information: type: array description: Information about the countries supported by the store. items: $ref: '#/components/schemas/Country' supported_languages: type: array description: Information about the languages supported by the store. items: $ref: '#/components/schemas/SupportedLanguage' general_settings: $ref: '#/components/schemas/GeneralSettings' alternative_payment_methods: type: array description: Any additional payment methods that are configured on the store and are not the default payment method (set in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4)). Objects in this array may have differing formats based on the payment gateway they are associated with. Province: title: Province type: object properties: iso_code: type: string description: The province code, using [ISO-3166](https://www.iso.org/iso-3166-country-codes.html) format. example: MB name: type: string description: The human-readable name of the province. example: Manitoba valid_for_shipping: type: boolean description: Indicates whether this province can be shipped to. example: true valid_for_billing: type: boolean description: Indicates whether this province can be used for billing addresses. example: true Country: title: Country type: object properties: iso_code: type: string description: The country code, using [ISO-3166](https://www.iso.org/iso-3166-country-codes.html) format. example: CA name: type: string description: The human-readable name of the country. example: Canada show_province: type: boolean description: Indicates whether this country should display the province field when the customer is entering address information. example: true province_label: type: string description: A label used to describe the region, such as State, Province, or Region. example: Province show_postal_code: type: boolean description: Indicates whether the country requires postal codes in addresses. example: true provinces: type: array description: List of provinces is applicable. items: $ref: '#/components/schemas/Province' valid_for_shipping: type: boolean description: Indicates whether this country can be shipped to. example: true valid_for_billing: type: boolean description: Indicates whether this country can be used for billing addresses. example: true Transaction: title: Transaction type: object description: '' properties: gateway: type: string description: | Name of the payment gateway this transaction was processed on. gateway_id: type: string description: Identifier for the payment gateway this transaction was processed on. amount: description: The amount, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. type: number transaction_id: type: string description: Payment gateway transaction ID. response_code: type: string description: Additional payment gateway response code. gateway_error: type: string description: The error message returned by the payment gateway. status: description: 'Status of the transaction. Possible values: failed, success.' type: string gateway_meta_data: type: object payment_id: type: string gateway_response: type: object JWTToken: type: string title: JWT Token description: The JSON Web Token (JWT) generated during the initialization of the order. Use the JWT to authenticate future calls to the [Checkout Frontend API](checkout). example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoX3R5cGUiOiJWMl9BUEkiLCJwYXlsb2FkIjp7InB1YmxpY19vcmRlcl9pZCI6Inlyb0Y2NDNNeUpTZVZRUUpES2R2c2QxYXdXY3BpRVFJbkhOaTJkWlhmWW9PdVI0dmFGVUhpNHBPRG9pRWFpOVQifSwiZXhwIjoxNjMyMzQxMjg3LCJuYmYiOm51bGwsImlhdCI6bnVsbH0.swmYcVBHyK2i86jN-bIOL3WOCzP5VQVLq9Ev-TfIC_c PublicOrderId: title: Public Order ID type: string description: The public order identifier generated when the order is initialized by making a request to the [Initialize Order](orders#operation/InitializeOrder) endpoint. example: nPTPIlIahDoEgZFabZNNvg7uxahLkGb1x4UINz3eqYV3eHewsjq7kubZc5BLAUqC ApplicationState: title: Application State type: object description: |- Represents the current state of the order. Taxes and discounts represent the summation of all tax or discount lines that have been applied anywhere through the order. Consulting the line items allows you to get the specific product break down of taxes and discounts. properties: customer: description: The customer that placed the order. oneOf: - $ref: '#/components/schemas/Customer' - type: array title: No customer maxItems: 0 addresses: type: object description: The billing and shipping addresses on the order. properties: shipping: description: The shipping address on the order. oneOf: - $ref: '#/components/schemas/Address' - type: array title: No address maxItems: 0 billing: description: The billing address on the order. oneOf: - $ref: '#/components/schemas/Address' - type: array title: No address maxItems: 0 line_items: type: array description: The list of line items associated with an order. Each line item includes information about the selected product and the taxes, fees, and discounts applied to it. items: type: object properties: product_data: $ref: '#/components/schemas/LineItem' taxes: type: array description: Any taxes that apply to the line item. items: $ref: '#/components/schemas/Tax' fees: type: array description: Any fees that apply to the line item. items: $ref: '#/components/schemas/LineItemFee' discounts: type: array description: Any discounts that apply to the line item. items: $ref: '#/components/schemas/Discount' fulfilled_quantity: type: integer description: The quantity of the line item that has been fulfilled. Fulfill a line item using the [Update Line Item](orders#operation/UpdateLineItem) endpoint. example: 2 fees: type: array description: Any fees that apply to the full order. items: $ref: '#/components/schemas/GeneralFee' taxes: type: array description: Any taxes that apply to the full order. items: $ref: '#/components/schemas/Tax' discounts: type: array description: Any discounts that apply to the full order. items: $ref: '#/components/schemas/Discount' payments: type: array description: The payments applied to the order. items: $ref: '#/components/schemas/Payment' order_total: type: number description: The total amount of the order (after tax, shipping, and discounts) using cents/base currency units using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 4700 order_meta_data: $ref: '#/components/schemas/OrderMetaData' shipping: type: object description: The shipping information — including shipping lines, taxes, and discounts — associated with an order. properties: selected_shipping: $ref: '#/components/schemas/ShippingLine' available_shipping_lines: type: array description: The shipping lines available for the order. items: type: object properties: id: type: string line: $ref: '#/components/schemas/ShippingLine' taxes: description: Any taxes that apply to the shipping rate. oneOf: - type: array items: $ref: '#/components/schemas/Tax' - type: number discounts: description: Any discounts that apply to the shipping rate. oneOf: - type: array items: $ref: '#/components/schemas/Discount' - type: number resumable_link: $ref: '#/components/schemas/ResumableLink' flow_id: type: string nullable: true description: The identifier of the origin checkout flow used to create the order. If left empty, defaults to `null` and is displayed as "Unassigned" in the Checkout admin. example: external-company-one-page-template currency: $ref: '#/components/schemas/Currency' display_currency: $ref: '#/components/schemas/DisplayCurrency' display_exchange_rate: $ref: '#/components/schemas/DisplayExchangeRate' created_via: type: string description: The source of the order. Plugin developers can use the [Set Order Created By](/guides/checkout/references/plugin-actions#set_order_created_by) action to set this field and indicate that an order was created by their plugin. If the order was created as normal through Bold Checkout, this value is `"checkout"`. example: My_Order_Creating_Plugin is_processed: type: boolean description: Indicates whether the order has been processed. example: false order_id: type: number description: Bold Checkout's internal order ID. example: 79047599 platform_order_id: type: string nullable: true description: A platform-generated identifier for the order. example: 1389wjfalsdf9y4r Customer: title: Customer type: object description: An authenticated or guest customer associated with an order. properties: platform_id: type: string description: The platform identifier for an authenticated customer. For guest customers, the value for this property will be null. nullable: true example: '50942578465125' public_id: type: string description: The public identifier generated by Checkout for a customer. nullable: true readOnly: true example: pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA first_name: type: string description: The first name of the customer. example: John last_name: type: string description: The last name of the customer. example: Doe email_address: type: string description: The email address of the customer. example: john.doe@example.com accepts_marketing: type: boolean description: If the customer would like to receive any sort of marketing emails. Defaults to `false`. example: true saved_addresses: type: array description: The saved addresses of an authenticated customer stored from the platform. items: $ref: '#/components/schemas/Address' required: - email_address SupportedLanguage: title: Supported Language type: object description: '' properties: id: type: integer description: Identifier of the language record. readOnly: true example: 32856 shop_id: type: integer description: The identifier of the shop associated to the language record. example: 1091521 iso_language: type: string description: A two character language code, using [ISO 639-1](https://www.iso.org/iso-639-language-codes.html). example: en language_name: type: string description: A human-readable name of the language. example: English language_blob: type: string description: The shop language details returned as stringified JSON. example: '{"language_name":"English","terms":{"customer_information":{"already_have_an_account":"Already have an account with us?","customer_info":"Customer information","email":"Email","email_address":"Email address","email_address_placeholder":"Email address","enter_new_address":"Enter a new address","log_in":"Log in","not_you":"Not you?","return_to_cart":"Return to cart","return_to_store":"Return to store","accepts_marketing":"Subscribe to our newsletter"},"shipping_address":{"address2_field":"Apt, suite, etc.","address2_field_optional":"Apt, suite, etc. (optional)","address_field":"Address","city_field":"City","company_field":"Company","company_field_optional":"Company (optional)","cont_to_shipping":"Continue to shipping method","country_field":"Country","country_field_placeholder":"Choose a country","first_name_field":"First name","last_name_field":"Last name","optional":" (optional)","phone_field":"Phone","phone_field_optional":"Phone (optional)","postal_code_field":"Postal code","province":"Province","province_field":"Province","province_field_placeholder":"Choose a province","select_address":"Select an address","select_exist_address":"Select an existing address","shipping":"Shipping","shipping_address":"Shipping address","state":"State"}}}' is_default: type: boolean description: Indicates whether the given language is the shop default. example: true out_of_date: type: integer minimum: 0 maximum: 1 description: An integer (0 or 1) representing whether the given language blob is out of date, where 1 is out of date. example: 0 enabled: type: integer minimum: 0 maximum: 1 description: An integer (0 or 1) representing whether the given language blob is enabled on the shop, where 1 is enabled. example: 1 source: type: string nullable: true enum: - yappn - null description: The source of where the language is managed, where `null` implies a language managed within Checkout Admin. example: null created_at: type: string format: date-time description: The date and time when the language record was created. example: '2021-08-12T14:30:54.000000Z' updated_at: type: string format: date-time description: The date and time when the language record was last updated. example: '2022-10-20T19:54:08.000000Z' deleted_at: type: string format: date-time nullable: true description: The date and time when the language record was deleted, where `null` implies an active record. example: null name: type: string description: A human-readable name of the language. example: English shop_language_id: type: integer description: The identifier of the language record. readOnly: true example: 32856 Address: title: Address description: A shipping or billing address. type: object nullable: true properties: id: type: string description: A unique identifier of the address. nullable: true readOnly: true example: '123' first_name: type: string description: The first name of the addressee. example: John last_name: type: string description: The last name of the addressee. example: Doe address_line_1: type: string description: The street address. example: 50 Fultz Blvd address_line_2: type: string description: 'Any additional street address details (apt #, suite #, etc).' example: Suite 200 country: type: string description: The country name. example: Canada city: type: string description: The city name. example: Winnipeg province: type: string description: The province or state name, if applicable. example: Manitoba country_code: type: string description: The country code, in [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) format. example: CA province_code: type: string description: The province or state code, in [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) format, if applicable. example: MB postal_code: type: string description: The postal/zip code. Required for most countries, including the United States, Canada, and Mexico. Validated on format only when provided. example: R3Y0L6 business_name: type: string description: If applicable, the business name. example: Acme Inc. phone_number: type: string description: The phone number of the addressee. example: '8005550101' required: - country - country_code ShippingLine: title: Shipping Line type: object nullable: true properties: id: type: string description: The index of the shipping line. example: '0' description: type: string description: A description of the shipping line. example: 'Custom weight-based rate: tier 2' amount: type: number description: The shipping amount represented in cents/base currency units using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 450 code: type: string description: An identifier assigned to the shipping rate by the shipping provider. example: EXPID Payment: title: Payment type: object properties: gateway_public_id: type: string description: A public identifier of the payment gateway used with the payment. example: i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW amount: type: number description: The payment amount, represented in cents/base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 4700 currency: type: string description: The currency of the payment, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: CAD type: type: string description: The payment gateway that accepted the payment. example: spreedly display_string: type: string description: A description of the payment to visually display to the customer. example: Credit Card Payment id: type: string readOnly: true description: An identifier of the payment. example: '' token: type: string description: A token generated by the payment gateway to identify the payment. example: 7uZAMRAf80KiEwibsrrM5IB41yU retain: type: boolean description: Indicates whether the payment method will be saved for future orders. Checkout only stores a tokenized version of the payment method. default: false example: false required: - gateway_public_id - token Error: title: error type: object properties: message: type: string description: The message for the error. example: The first name field is required. type: type: string description: The type of error that occurred. example: customer field: type: string description: The field of the object that the error was found in. example: first_name severity: type: string description: The severity of the error. example: validation sub_type: type: string description: The sub_type of the error. example: order ErrorV2: title: Error type: object properties: code: type: string description: The code for the error. example: 11-13 type: type: string description: The type of error. example: integration_config.shop_could_not_be_determined message: type: string description: The message for the error. example: shop could not be determined details: type: object description: Additional details for the error. example: {} UnprocessableEntity: description: There was a problem with the object provided in the request. type: object properties: errors: type: array items: type: object properties: message: type: string description: An error message describing what went wrong. example: The first name field is required. type: type: string description: The type of error that occurred. example: customer field: type: string description: The field of the object that the error was found in. example: first_name severity: type: string description: The severity of the error. example: validation sub_type: type: string description: The sub_type of the error. example: order ResumableLink: type: string nullable: true description: A URL used to resume an order. If provided, the default resumable link generated by Checkout will be overwritten with this URL. This resumable link will be provided in the email and webhook for an abandoned checkout. example: https://mycheckout.com/resume GeneralSettings: title: General Settings description: General Checkout settings, which can be configured in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4). type: object properties: checkout_process: type: object description: General settings relevant to the checkout process properties: company_name_option: type: string description: Indicates whether company name is required on an order. enum: - optional - required - hidden example: hidden phone_number_required: type: boolean description: Indicates whether phone number is required on an order. example: false accepts_marketing_checkbox_option: type: string description: Indicates initial display of email marketing options. enum: - checked - unchecked - hidden example: unchecked address_autocomplete: type: object description: The configuration for address autocomplete functionality, if enabled for the particular shop. properties: provider: type: string nullable: true description: The data provider for address autocomplete. enum: - google - loqate example: google api_key: type: string nullable: true description: A public API key for querying the address autocomplete provider. example: awefa9304q9wfqf43jfaw904kfwkaslserfa94 required: - checkout_process Tax: title: Tax type: object properties: value: type: number description: The value of the tax applied, represented in cents/base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 1000 name: type: string description: A descriptor of the tax being applied. example: GST is_included: type: boolean description: Indicates whether the tax is already included in the price. example: true FlowId: type: string nullable: true maxLength: 255 description: |- An identifier for the origin checkout flow that created the order. The field is optional for custom checkout flows and other clients, but provides a convenience for determining the order's origin. Bold-hosted templates provide this field and are identified by the first 4 letters `"bold"`, which are reserved. The value `"unassigned"` is reserved for when the field is not provided. For more information, refer to [Checkout Flows](/guides/checkout/concepts/flows) example: external-company-one-page-template ApiSessionId: type: string maxLength: 255 description: |- An optional alphanumeric identifier used to group orders for the purpose of tracking order completion rates. If this value is not provided, Bold generates one randomly and assumes that the order is not grouped with any others. For more information, refer to [Configure Checkout Flow Metrics](/guides/checkout/metrics). example: abc123 RefundRequestFull: title: Refund Request description: Request body for full refunds. type: object properties: reason: type: string description: The note attached to the refund. example: Product arrived broken. email_notification: type: boolean description: Whether or not Checkout will send an email notification. If true, an email will be sent. example: true refund_order_data: type: object description: (optional) Additional refund transaction data for specific payment gateway integrations. example: data: external_id: legacy-id-135798642 RefundRequest: title: Refund Request description: Request body for partial refunds. type: object allOf: - $ref: '#/components/schemas/RefundRequestFull' - type: object properties: amount: type: integer description: Total amount requested for refund, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 6055 RefundResponse: title: Refund Response description: Response body for refunds. type: object properties: amount_refunded: type: integer description: The refund amount issued, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 6055 transaction_details: type: array description: Details for the refund transaction. items: $ref: '#/components/schemas/RefundTransaction' RefundTransaction: title: RefundTransaction type: object properties: success: type: boolean description: If the transaction was successful. example: true transaction_number: type: string description: The transaction number. example: ch_1GvDW4JhIKSKpq8w9SoshRef amount: type: integer description: The amount refunded in the transaction, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 6055 created_at: type: string description: The datetime the transaction was created. example: '2021-01-15 01:01:01' errors: type: array description: The errors associated with the transaction. items: {} CapturePaymentRequest: title: Capture Payment Request type: object properties: reauth: type: boolean description: Whether or not Checkout should attempt to re-authorize payment if the authorize transaction has been used or expired. default: true example: true idempotent_key: type: string description: A unique idempotency key generated by the client which the server uses to recognize subsequent retries of the same requests. example: 2b268b6f-b3c0-4efb-9c43-1aa59d535182 capture_data: type: object description: Any data associated with the payment capture request. example: data: external_id: legacy-id-135798642 required: - reauth CapturePartialPaymentRequest: title: Capture Partial Payment Request type: object allOf: - $ref: '#/components/schemas/CapturePaymentRequest' - type: object properties: amount: type: number description: Amount to capture, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 120 required: - amount CapturePaymentResponse: title: Capture Payment Response type: object properties: order_total: type: number description: The total of the order, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 120 amount_remaining: type: number description: The amount remaining after a payment has been captured, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 60 paid_total: type: number description: The total payment captured, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 60 capture_held_total: type: number description: The total amount held for capture by the payment gateway, represented in base currency units, using [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) standards. example: 0 transactions: type: array description: The transactions created for the payment capture. items: $ref: '#/components/schemas/Transaction' example: - gateway: Stripe Default Name gateway_id: bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi amount: 60 transaction_id: ch_1GvDW4JhIKSKpq8w9SoshRef reference_transaction_id: null response_code: '' status: success payment_id: abc123 examples: cart_token: value: cart_id: 1snVSJAWYWWYhfLWq9ABcXMwx8mcvh2U access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c generic_cart: value: cart_items: - quantity: 2 title: Some Product weight: 50 taxable: true image: https://example.com/thing.jpg requires_shipping: true price: 2000 line_item_key: ABC123 line_item_properties: colour: red size: small customer: email_address: john.doe@example.com first_name: John last_name: Doe platform_id: '12345' saved_addresses: - id: '12' first_name: John last_name: Doe address_line_1: 50 Fultz Blvd address_line_2: '' province: Manitoba city: Winnipeg country_code: CA country: Canada province_code: MB postal_code: R3Y0L6 business_name: '' phone_number: '8005550101' order_meta_data: cart_parameters: cp-key1: A cart param note_attributes: na-key1: A note attribute notes: Special delivery message. tags: - order-1 gift_card_cart: value: cart_items: - id: 786dur quantity: 1 title: Gift Card variant_title: Gift Card $50 taxable: true image: https://example.com/thing.jpg requires_shipping: false price: 4700 line_item_key: ABC123 line_item_properties: recipient_name: John Doe recipient_email: johndoe@boldcommerce.com message: Dear John, Happy Birthday! custom_amount: '5000' customer: email_address: john.doe@example.com first_name: John last_name: Doe platform_id: '12345' saved_addresses: - id: '12' first_name: John last_name: Doe address_line_1: 50 Fultz Blvd address_line_2: '' province: Manitoba city: Winnipeg country_code: CA country: Canada province_code: MB postal_code: R3Y0L6 business_name: '' phone_number: '8005550101' order_meta_data: cart_parameters: cp-key1: A cart param note_attributes: na-key1: A note attribute notes: Special delivery message. tags: - order-1 sku_cart: value: cart_items: - sku: 123AB quantity: 3 line_item_key: ABC123 line_item_properties: colour: red size: small variant_id_cart: value: cart_items: - platform_id: '12345' quantity: 3 line_item_key: ABC123 line_item_properties: colour: red size: small authenticated_customer: value: customer: platform_id: '50942578465125' email_address: john.doe@example.com NoCustomer: summary: Deleted Customer value: data: application_state: customer: [] addresses: shipping: id: '123' first_name: John last_name: Doe address_line_1: 50 Fultz Blvd address_line_2: Suite 200 country: Canada city: Winnipeg province: Manitoba country_code: CA province_code: MB postal_code: R3Y0L6 business_name: Acme Inc. phone_number: '8005550101' billing: id: '123' first_name: John last_name: Doe address_line_1: 50 Fultz Blvd address_line_2: Suite 200 country: Canada city: Winnipeg province: Manitoba country_code: CA province_code: MB postal_code: R3Y0L6 business_name: Acme Inc. phone_number: '8005550101' line_items: - product_data: id: 724bca product_title: Oak Cheese Grater title: Small image_url: http://shop.images/oakcheesegrater properties: colour: red size: small description: A handmade oak cheese grater to elevate your cheese-eating experience. quantity: 2 price: 2350 total_price: 4700 visible: 1 line_item_key: oak_cheese_grater_2643 barcode: 1234ABC compare_at_price: 4000 weight: 1000 weight_unit: g product_id: oak-cheese-grater variant_id: oak-cheese-grater-small requires_shipping: true sku: OAK_GRATER_SM taxable: true tags: Kitchen, Cheese Board, Oak vendor: Cheese Boards Unlimited total_weight: 2000 - taxes: - value: 1000 name: GST is_included: true - fees: - amount: 500 name: Miscellaneous fee. - discounts: - code: SUMMER5 text: Summer discount code value: 500 source: coupon - fulfilled_quantity: 2 fees: - id: '123456789' line_text: Custom Fee — Added by Plugin fee_type: fixed value: 10 source: PLUGIN plugin_uuid: a52589f8-09df-11ed-b30e-f67072e164ee taxable: true show_description: true taxes: - value: 1000 name: GST is_included: true discounts: - code: SUMMER5 text: Summer discount code value: 500 source: coupon payments: - gateway_public_id: i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW amount: 4700 currency: CAD type: spreedly display_string: Credit Card Payment id: '' token: 7uZAMRAf80KiEwibsrrM5IB41yU retain: false order_total: 4700 order_meta_data: cart_parameters: key: cp-key1, property1: A cart param. property2: A cart param. note_attributes: key: na-key1 property1: A note attribute. property2: A note attribute. notes: A special delivery note. tags: - order-1 shipping: selected_shipping: id: '0' description: 'Custom weight-based rate: tier 2' amount: 450 code: EXPID available_shipping_lines: - id: string, line: id: '0' description: 'Custom weight-based rate: tier 2' amount: 450 code: EXPID taxes: - value: 1000 name: GST is_included: true discounts: - code: SUMMER5 text: Summer discount code value: 500 source: coupon resumable_link: string flow_id: external-company-one-page-template currency: iso_code: CAD iso_numeric_code: 124 symbol: $ format: ${{amount}} has_decimal: true show_iso_code: true created_via: My_Order_Creating_Plugin is_processed: false order_id: 79047599 platform_order_id: 1389wjfalsdf9y4r