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

Endpoint: PATCH /v2/order/{key} with status=AUTHORIZED

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}

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

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

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: PATCH /v2/order/{key}/refund with status=CANCELED

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.

📘

The company_id is required to create orders using this method.

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.