Payments API

Process payments via Stripe with PaymentIntents and handle webhook events.

POST/admin/payments/intent

Create a Stripe PaymentIntent for an order

Request Body

{
  "order_id": "order_789",
  "amount": 14999,
  "currency": "usd"
}

Response

{
  "success": true,
  "data": {
    "client_secret": "pi_3abc...secret_xyz",
    "payment_intent_id": "pi_3abc123"
  }
}
Bearer Token Required
POST/stripe/webhook

Stripe webhook endpoint for payment events (payment_intent.succeeded, charge.refunded, etc.)

Headers

Stripe-Signature: t=1234567890,v1=abc123...
Stripe Signature Verified

Subscription Billing API

Endpoints for managing your platform subscription (Starter / Professional / Business). Stripe Customer Portal handles plan changes, payment-method updates, cancellation, and invoice history.

GET/billing/status

Current subscription state for the dashboard banner.

Response

{
  "tier": "professional",
  "subscription_status": "active",
  "preferred_interval": "monthly",
  "trial_ends_at": null,
  "trial_extended_at": null,
  "current_period_end": "2026-06-26T00:00:00Z",
  "has_active_access": true,
  "has_card_on_file": true
}
Bearer Token Required
POST/billing/checkout

Promote a trialing account to a paid Stripe Subscription. Frontend tokenizes the card via Stripe Elements first; payment_method_id is the resulting pm_xxx.

Request Body

{
  "tier": "professional",
  "interval": "monthly",
  "payment_method_id": "pm_1234…",
  "customer_email": "billing@yourstore.com"
}
Bearer Token Required
POST/billing/portal-session

Open a Stripe-hosted Customer Portal session. Returns a short-lived URL the frontend redirects to.

Response

{ "url": "https://billing.stripe.com/p/session/..." }
Bearer Token Required

Coupons API

Create and manage discount codes with usage limits, expiration, and validation.

GET/admin/coupons

List all coupons

Response

{
  "success": true,
  "data": [
    { "id": "cpn_01", "code": "TEAM20", "discount_type": "percentage", "discount_value": 20, "usage_count": 12, "max_uses": 100, "expires_at": "2026-06-01T00:00:00Z" }
  ]
}
Bearer Token Required
POST/admin/coupons

Create a new coupon code

Request Body

{
  "code": "SPRING25",
  "discount_type": "percentage",
  "discount_value": 25,
  "max_uses": 50,
  "min_order_amount": 100.00,
  "expires_at": "2026-06-01T00:00:00Z"
}
Bearer Token Required
POST/admin/coupons/validate

Validate a coupon code against an order total

Request Body

{ "code": "SPRING25", "order_total": 150.00 }
Bearer Token Required

Store Credit API

Issue, track, and redeem store credit for customers.

POST /admin/store-credit/issue

Issue store credit to a customer

Request Body

{
  "customer_id": "cust_123",
  "amount": 50.00,
  "reason": "refund",
  "reference": "order_789",
  "expiration_date": "2026-12-31"
}

Response

{
  "success": true,
  "data": {
    "credit_id": "credit_001",
    "customer_id": "cust_123",
    "amount": 50.00,
    "balance_remaining": 50.00,
    "issued_at": "2026-03-20T10:00:00Z"
  }
}
Bearer Token Required
GET /admin/store-credit/balance/{customer_id}

Get store credit balance for a customer

Response

{
  "success": true,
  "data": {
    "customer_id": "cust_123",
    "total_issued": 100.00,
    "total_used": 30.00,
    "balance_remaining": 70.00
  }
}
Bearer Token Required

Gift Cards API

Create, manage, and redeem gift cards with batch operations.

POST /admin/gift-cards

Create a single gift card

Request Body

{
  "amount": 100.00,
  "currency": "USD",
  "recipient_email": "john@example.com",
  "message": "Happy Birthday!",
  "expiration_date": "2027-03-20"
}

Response

{
  "success": true,
  "data": {
    "gift_card_id": "gc_001",
    "code": "GC-ABC-DEF-123",
    "amount": 100.00,
    "balance": 100.00,
    "created_at": "2026-03-20T10:00:00Z"
  }
}
Bearer Token Required
POST /admin/gift-cards/batch

Create multiple gift cards in batch

Request Body

{
  "quantity": 100,
  "amount": 50.00,
  "currency": "USD",
  "expiration_date": "2027-03-20"
}

Response

{
  "success": true,
  "data": {
    "batch_id": "batch_001",
    "cards_created": 100,
    "download_url": "https://api.marcsinventory.com/files/gift_cards_batch_001.csv"
  }
}
Bearer Token Required
GET /admin/gift-cards/lookup

Look up a gift card by code

Query Parameters

?code=GC-ABC-DEF-123

Response

{
  "success": true,
  "data": {
    "code": "GC-ABC-DEF-123",
    "balance": 75.00,
    "original_amount": 100.00,
    "status": "active"
  }
}
Bearer Token Required
POST /admin/gift-cards/redeem

Redeem a gift card in an order

Request Body

{
  "code": "GC-ABC-DEF-123",
  "order_id": "order_999",
  "amount_to_redeem": 75.00
}

Response

{
  "success": true,
  "data": {
    "transaction_id": "txn_001",
    "amount_redeemed": 75.00,
    "balance_remaining": 0.00,
    "redeemed_at": "2026-03-20T11:00:00Z"
  }
}
Bearer Token Required

Returns API

Full return lifecycle: create, approve, receive, and refund with RMA tracking.

GET/admin/returns

List all returns with status filtering

Query Parameters

?status=pending&limit=50&offset=0

Response

{
  "success": true,
  "data": [
    { "id": "ret_001", "order_id": "order_789", "status": "pending", "reason": "wrong_size", "total_refund": 29.99, "created_at": "2026-03-21T09:00:00Z" }
  ]
}
Bearer Token Required
POST/admin/returns

Create a return request for an order

Request Body

{
  "order_id": "order_789",
  "items": [{ "order_item_id": "item_01", "quantity": 1, "reason": "wrong_size" }],
  "refund_method": "store_credit"
}
Bearer Token Required
PUT/admin/returns/{return_id}/approve

Approve a pending return and generate RMA label

Response

{
  "success": true,
  "data": {
    "return_id": "ret_001",
    "status": "approved",
    "rma_label_url": "https://..."
  }
}
Bearer Token Required