Instica API — Subscriptions

Plans

GET List plans

/api/v1/subscriptions/plans/

Returns all available subscription plans with pricing and feature details.

Plan fields

Field	Type	Description
`uid`	string	Plan identifier
`name`	string	Plan name (e.g., "Pro", "Business")
`slug`	string	URL-safe plan slug
`description`	string	Plan description
`price_monthly`	string	Monthly price (decimal)
`price_yearly`	string	Yearly price (decimal)
`currency`	string	ISO 4217 currency code
`features`	object[]	Feature list with limits
`is_popular`	boolean	Highlighted plan flag
`stripe_monthly_price_id`	string	Stripe Price ID for monthly billing
`stripe_yearly_price_id`	string	Stripe Price ID for yearly billing

Request

curl https://app.instica.com/api/v1/subscriptions/plans/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response — 200 OK

[
  {
    "uid": "plan_pro",
    "name": "Pro",
    "slug": "pro",
    "description": "For growing sellers",
    "price_monthly": "19.99",
    "price_yearly": "199.99",
    "currency": "USD",
    "features": [
      {
        "name": "Inventory items",
        "limit": 5000
      },
      {
        "name": "Marketplace connections",
        "limit": 5
      }
    ],
    "is_popular": true,
    "stripe_monthly_price_id": "price_1N...",
    "stripe_yearly_price_id": "price_1N..."
  }
]

Subscription status

GET Get status

/api/v1/subscriptions/status/

Returns the current subscription state, active plan details, usage, and billing provider.

Status fields

Field	Type	Description
`is_active`	boolean	Whether subscription is active
`plan`	object	Current plan details (or `null`)
`billing_provider`	string	`stripe`, `apple`, or `none`
`current_period_end`	string	ISO 8601 period end date
`cancel_at_period_end`	boolean	Whether cancellation is pending
`trial_end`	string \| null	Trial end date if applicable
`usage`	object	Current usage vs plan limits

Response — 200 OK

{
  "is_active": true,
  "plan": {
    "uid": "plan_pro",
    "name": "Pro",
    "slug": "pro"
  },
  "billing_provider": "stripe",
  "current_period_end": "2025-02-15T00:00:00Z",
  "cancel_at_period_end": false,
  "trial_end": null,
  "usage": {
    "inventory_items": 1234,
    "inventory_limit": 5000,
    "marketplace_connections": 3,
    "marketplace_limit": 5
  }
}

Apple In-App Purchase

iOS app subscriptions are managed through App Store. The API provides endpoints for account tokens and transaction syncing.

Endpoint	Method	Description
`/api/v1/subscriptions/apple/account-token/`	GET	Get account token for StoreKit
`/api/v1/subscriptions/apple/transactions/`	POST	Submit App Store transaction

iOS only: These endpoints are called by the Instica Inventory iOS app during purchase flows. Direct API calls are not required for Stripe subscribers.

Account token response

Field	Type	Description
`account_token`	string	UUID token for StoreKit purchase attribution

Get account token

curl https://app.instica.com/api/v1/subscriptions/apple/account-token/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response — 200 OK

{
  "account_token": "550e8400-e29b-41d4-a716-446655440000"
}

Submit transaction

curl -X POST \
  https://app.instica.com/api/v1/subscriptions/apple/transactions/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "2000000123456789",
    "original_transaction_id": "2000000123456789"
  }'

Stripe billing

Web and API subscribers use Stripe for billing. These endpoints manage checkout sessions, customer portals, and subscription lifecycle.

Endpoint	Method	Description
`/api/v1/subscriptions/stripe/checkout/`	POST	Create a Stripe Checkout session
`/api/v1/subscriptions/stripe/portal/`	POST	Create a billing portal session
`/api/v1/subscriptions/stripe/details/`	GET	Get Stripe subscription details
`/api/v1/subscriptions/stripe/reactivate/`	POST	Reactivate cancelled subscription

Checkout request body

Field	Type	Required	Description
`price_id`	string	Yes	Stripe Price ID from the plans endpoint
`success_url`	string	No	Redirect URL after success
`cancel_url`	string	No	Redirect URL on cancel

Checkout response

Field	Type	Description
`checkout_url`	string	Stripe Checkout session URL — redirect user here
`session_id`	string	Stripe Session ID for tracking

Create checkout

curl -X POST \
  https://app.instica.com/api/v1/subscriptions/stripe/checkout/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price_id": "price_1NxyzMonthly",
    "success_url": "https://app.instica.com/settings/billing?success=true",
    "cancel_url": "https://app.instica.com/pricing"
  }'

Response — 200 OK

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "cs_live_a1b2c3..."
}

Create billing portal

curl -X POST \
  https://app.instica.com/api/v1/subscriptions/stripe/portal/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response: { "portal_url": "https://billing.stripe.com/p/session/..." }

Reactivate

curl -X POST \
  https://app.instica.com/api/v1/subscriptions/stripe/reactivate/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response: { "status": "active", "cancel_at_period_end": false }

Payment methods

Endpoint	Method	Description
`/api/v1/subscriptions/stripe/payment-methods/`	GET	List payment methods

Payment method fields

Field	Type	Description
`id`	string	Stripe PaymentMethod ID
`type`	string	`card`, `us_bank_account`, etc.
`card`	object	Card details (brand, last4, exp_month, exp_year)
`is_default`	boolean	Whether this is the default payment method

Response — 200 OK

[
  {
    "id": "pm_1Nxyz...",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2026
    },
    "is_default": true
  }
]

Invoices

Endpoint	Method	Description
`/api/v1/subscriptions/stripe/invoices/`	GET	List invoices

Invoice fields

Field	Type	Description
`id`	string	Stripe Invoice ID
`status`	string	`paid`, `open`, `void`, `uncollectible`
`amount_due`	integer	Amount in cents
`currency`	string	ISO 4217 currency code
`created`	integer	Unix timestamp
`hosted_invoice_url`	string	URL for the hosted invoice page
`invoice_pdf`	string	URL to download the invoice PDF

Response — 200 OK

[
  {
    "id": "in_1Nxyz...",
    "status": "paid",
    "amount_due": 1999,
    "currency": "usd",
    "created": 1706140800,
    "hosted_invoice_url": "https://invoice.stripe.com/i/...",
    "invoice_pdf": "https://pay.stripe.com/invoice/..."
  }
]

Previous User & Account Next Organization →

Subscriptions API

Plans

GET List plans

Plan fields

Subscription status

GET Get status

Status fields

Apple In-App Purchase

Account token response

Stripe billing

Checkout request body

Checkout response

Payment methods

Payment method fields

Invoices

Invoice fields