The Orders endpoints provide a way to manage the lifecycle of a Credit Key order after the hosted checkout session has been created or when an order is created directly from an ERP or In-store context. These endpoints allow you to authorize, update, cancel, capture, and refund orders so your e-commerce or ERP system stays aligned with Credit Key’s records.

This page provides a high-level overview of when to call each endpoint.

Order Lifecycle Summary

A typical Credit Key order follows these steps:

1. Created via POST /v2/hosted/checkout
2. Authorized via PATCH /v2/order/{key} with status=AUTHORIZED
3. Updated before fulfillment
4. Captured when the order ships
5. Refunded if adjustments or returns occur

The {key} value (the Credit Key order key) is required for all operations.

Orders API Endpoints

Authorize an Order

Called immediately after the customer returns to your site from hosted checkout.

Your system should:

• Read the CKKEY from the return URL
• Call the authorize endpoint
• Only create/place the order in your system if authorization succeeds

If authorization fails, do not create the order.

Update an Order

Endpoint

PATCH /v2/order/{key}

API Reference: https://docs.creditkey.com/reference/ordercontroller_update_v2

Use this for any order changes before capture, including:

• Updated totals or discounts
• Line-item changes
• Quantity adjustments
• Merchant order ID assignment
• Internal order status updates
• Supported metadata

Amount changes cannot be made after capture.

Cancel an Order

Endpoint

PATCH /v2/order/{key} with status='CANCELED'

API Reference: https://docs.creditkey.com/reference/ordercontroller_update_v2

Use this when an order is canceled before shipment.

A canceled order:

• Cannot be captured
• Is removed as an active financing obligation in the customer’s account

Common scenarios include customer cancellations, out-of-stock items, or fraud checks.

Capture an Order (Ship an Order)

Endpoint

PATCH /v2/order/{key} with status='CAPTURED'

API Reference: https://docs.creditkey.com/reference/ordercontroller_update_v2

Capture the authorized amount when the order ships.

Requirements:

• Merchant order ID must be included before or during capture
• Totals cannot be changed at this stage
• Multi-shipment flows may be supported depending on configuration

Capture should always align with your fulfillment/shipment event.

Refund an Order

Endpoint

POST /v2/order/{key}/refund

API Reference: https://docs.creditkey.com/reference/ordercontroller_refund_v2

Use this endpoint to issue full or partial refunds after capture.

Reasons may include:

• Returned items
• Price adjustments
• Shipping corrections
• Partial or full order reversals

Refunds update the customer’s repayment schedule.

Best Practices

• Capture only after shipment (never auto-capture at authorization).
• Sync order updates before capture to ensure accurate records.
• Store the Credit Key order key for later operations.
• Use webhooks to receive asynchronous order status notifications.

Order Statuses

Creating Orders via Orders API(Not via Hosted Checkout)

This method requires that a borrower has a default term selected for their account.

Your Solutions Engineer can provide you with an 'Apply Now' link which you can display on your website or include in marketing emails. Using this link, your customers can apply for a credit line with Credit Key and select default loan terms. You can subscribe to webhooks to receive a notification whenever a company applies and is approved. Once the user has gone through our application flow, you can create orders directly via the API without redirecting the user away from your checkout screen. Credit Key will already have all the necessary company information, an underwriting decision, and the borrower's default loan terms to place the order.

POST /order - API Reference

Pass the company id and order information to create a Credit Key order. You'll use the order key returned in the response for post order management.

Partial Capture Overview

Partial capture lets you ship and bill an order in pieces while keeping a single original Credit Key authorization. Instead of capturing the full financed amount when the order is first fulfilled, you can create partial captures as items ship, each tied back to the original order.

The /v2/order/{key}/partial endpoint is used to create one of these partial child orders against an existing, approved Credit Key order.

Endpoint

POST /v2/order/{key}/partial

API Reference: https://docs.creditkey.com/reference/ordercontroller_createpartial_v2

When to Use Partial Capture

• The order will be fulfilled in multiple shipments (e.g., items ship from different warehouses).
• Part of the order is backordered or delayed, but you want to capture what has shipped now.
• You need to bill and reconcile shipments separately while preserving a single financing approval and total credit line.

In each of these cases, you don’t want to cancel and re-authorize the order; instead, you capture only the shipped portion and leave the remaining authorization open for later captures.

How Partial Capture Works

1. Customer is approved and original order is authorized

   • You create and authorize an order via the v2 Orders API.
   • Credit Key approves an amount (the total financed value) and holds that as an authorization.

2. You ship a subset of items

   • When a partial shipment is ready, you determine the amount to capture for that shipment (based on line items, taxes, and shipping you want to bill now).

3. Create a partial capture using /v2/order/{key}/partial

   • You call the partial-capture endpoint with:

     • A reference to the original (parent) order(CKID).
     • The capture amount for this shipment.
     • Optional merchant metadata references such as shipment ID, invoice number, or internal order references.

   • Credit Key creates a partial child order representing just this captured portion.

4. Remaining authorization is updated

   • The original order’s remaining authorized balance is reduced by the captured amount.
   • The remaining balance can be used for future partial captures (additional shipments) until you’ve captured the full approved amount or voided the remainder.

5. Subsequent shipments → additional partial captures

   • For each additional shipment, you repeat the process with the new capture amount and references.
   • Each call generates another partial child order and further reduces the remaining authorization.

6. Final shipment or unused balance

   • When all items are shipped, the sum of all partial captures should match the original approved amount.
   • If there is some amount you will never ship, you can void the remaining authorization (using the appropriate void/close endpoint) so that no extra funds remain held.

Benefits of Partial Capture

• Align financing with fulfillment – Only capture what you actually ship.
• Better customer experience – The customer’s financed amount mirrors real shipments rather than the original quote when parts are delayed or cancelled.
• Cleaner reconciliation – Each partial capture can be tied to a specific shipment or invoice, making settlement reports and ERP posting easier.
• No re-authorization required – You avoid repeated credit checks and approvals for each shipment; everything is managed under the original order’s authorization.

What's Next

Once you've implemented partial captures, the next step is to automate your integration by receiving notifications from Credit Key.

Webhooks allow your application to receive real-time events for order lifecycle changes, reducing the need to poll the API and helping keep your systems synchronized.

Continue to Webhooks to learn how to configure webhook endpoints, validate incoming requests, and process Credit Key events.