Skip to main content

Create a checkout

POST /v1/checkout creates a hosted provider checkout for an existing customer. Use exactly one checkout target: planId for a subscription or creditPackId for a one-time credit purchase.

Node.js SDK​

import { Usagey } from "@usagey/sdk";

const usagey = new Usagey(process.env.USAGEY_API_KEY!);

const checkout = await usagey.checkout.create(
  {
    customerId: 'cus_123',
    creditPackId: 'pack_credits_10k',
    successUrl: 'https://app.example.com/billing/success',
    cancelUrl: 'https://app.example.com/billing/cancel',
  },
  {idempotencyKey: 'credit-order-456'},
);

redirect(checkout.checkoutUrl);

For a plan checkout, replace creditPackId with planId.

REST​

curl --request POST https://sandbox.usagey.com/v1/checkout \
  --header "Authorization: Bearer $USAGEY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: subscription-order-123" \
  --data '{
    "customerId": "cus_123",
    "planId": "plan_growth",
    "successUrl": "https://app.example.com/billing/success",
    "cancelUrl": "https://app.example.com/billing/cancel"
  }'

Behavior​

  • The API key, customer, target, and provider connection must belong to the same Sandbox or Production workspace.
  • Usagey selects the oldest active provider connection unless providerConnectionId is supplied.
  • Reusing an idempotency key with the same body returns the original checkout and sets replayed: true.
  • Reusing an idempotency key with a different body returns 409.
  • Usagey appends org, organizationId, env, and mode query parameters to the return URLs without replacing existing query parameters.
  • Checkout completion remains webhook-driven. Creating a checkout does not activate a subscription or credit balance by itself.

Keep this call on your server. Never expose a usg_test_ or usg_live_ key in browser code.