560 lines
17 KiB
YAML
560 lines
17 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: Autumn API
|
|
description: API to interact with Autumn
|
|
license:
|
|
name: MIT
|
|
version: 1.0.0
|
|
servers:
|
|
- url: https://api.useautumn.com/v1
|
|
security:
|
|
- bearerAuth: [Authorization]
|
|
paths:
|
|
/customers:
|
|
get:
|
|
security:
|
|
- secretKeyAuth: []
|
|
summary: List customers
|
|
description: Retrieve a paginated list of customers
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 10
|
|
maximum: 100
|
|
default: 10
|
|
description: Maximum number of customers to return
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
description: Number of customers to skip before returning results
|
|
x-code-samples:
|
|
- lang: typescript
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const { data } = await autumn.customers.list({ limit: 10, offset: 0 });
|
|
|
|
- lang: curl
|
|
source: |
|
|
curl 'https://api.useautumn.com/v1/customers?limit=10&offset=0' \
|
|
-H 'Authorization: Bearer am_sk_1234567890'
|
|
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Customer"
|
|
total:
|
|
type: integer
|
|
description: Total number of customers available
|
|
limit:
|
|
type: integer
|
|
description: Maximum number of customers returned
|
|
offset:
|
|
type: integer
|
|
description: Number of customers skipped before returning results
|
|
post:
|
|
description: Create a new Autumn customer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- id
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
email:
|
|
type: string
|
|
description: Customer's email address
|
|
name:
|
|
type: string
|
|
description: Customer's name
|
|
fingerprint:
|
|
type: string
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
|
|
x-code-samples:
|
|
- lang: typescript
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const { data } = await autumn.customers.create({
|
|
id: 'user_123',
|
|
name: 'John Yeo',
|
|
email: 'john@example.com'
|
|
});
|
|
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/customers' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"id": "user_123",
|
|
"name": "John Yeo",
|
|
"email": "john@example.com"
|
|
}'
|
|
- lang: python
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
customer = await autumn.customers.create(
|
|
id='user_123',
|
|
name='John Yeo',
|
|
email='john@example.com'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
example:
|
|
$ref: "#/components/examples/CustomerResponse/value"
|
|
|
|
/customers/{customer_id}:
|
|
get:
|
|
security:
|
|
- secretKeyAuth: []
|
|
summary: Get customer details
|
|
description: Retrieve detailed information about a specific customer including their subscriptions, add-ons, and entitlements
|
|
parameters:
|
|
- name: customer_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
- name: expand
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: ["invoices", "rewards", "trials_used", "entities", "referrals", "payment_method"]
|
|
style: form
|
|
explode: false
|
|
description: Array of additional data to include in the customer response. Options include invoices, rewards, trials_used, entities, referrals, payment_method
|
|
x-code-samples:
|
|
- lang: typescript
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const { data } = await autumn.customers.get('user_123');
|
|
|
|
- lang: curl
|
|
source: |
|
|
curl 'https://api.useautumn.com/v1/customers/user_123' \
|
|
-H 'Authorization: Bearer am_sk_1234567890'
|
|
|
|
- lang: python
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
customer = await autumn.customers.get('user_123')
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
example:
|
|
$ref: "#/components/examples/CustomerResponse/value"
|
|
post:
|
|
security:
|
|
- secretKeyAuth: []
|
|
summary: Update customer details
|
|
description: Update information for an existing customer
|
|
parameters:
|
|
- name: customer_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: New ID to update the customer to (eg if switching from user to org)
|
|
name:
|
|
type: string
|
|
description: The customer's full name
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: The customer's email address
|
|
fingerprint:
|
|
type: string
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
|
|
x-code-samples:
|
|
- lang: typescript
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const { data } = await autumn.customers.update('user_123', {
|
|
name: 'John Yeo',
|
|
email: 'john@example.com'
|
|
});
|
|
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/customers/user_123' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"name": "John Yeo",
|
|
"email": "john@example.com"
|
|
}'
|
|
|
|
- lang: python
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
customer = await autumn.customers.update(
|
|
customer_id='user_123',
|
|
name='John Yeo',
|
|
email='john@example.com'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
example:
|
|
$ref: "#/components/examples/CustomerResponse/value"
|
|
delete:
|
|
security:
|
|
- secretKeyAuth: []
|
|
summary: Delete a customer
|
|
description: Delete a customer
|
|
parameters:
|
|
- name: customer_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
- name: delete_in_stripe
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
description: Also delete the linked Stripe customer
|
|
x-code-samples:
|
|
- lang: typescript
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const { data } = await autumn.customers.delete('user_123', {
|
|
delete_in_stripe: true
|
|
});
|
|
|
|
- lang: curl
|
|
source: |
|
|
curl -X DELETE 'https://api.useautumn.com/v1/customers/user_123?delete_in_stripe=true' \
|
|
-H 'Authorization: Bearer am_sk_1234567890'
|
|
|
|
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
example:
|
|
$ref: "#/components/examples/CustomerResponse/value"
|
|
components:
|
|
examples:
|
|
CustomerResponse:
|
|
value:
|
|
autumn_id: "cus_2w5dzidzFD1cESxOGnn9frVuVcm"
|
|
created_at: 1677649423000
|
|
env: "production"
|
|
id: "user_123"
|
|
name: "John Yeo"
|
|
email: "john@example.com"
|
|
fingerprint: ""
|
|
stripe_id: "cus_abc123"
|
|
products:
|
|
[
|
|
{
|
|
id: "pro",
|
|
name: "Pro Plan",
|
|
group: "",
|
|
status: "active",
|
|
started_at: 1677649423000,
|
|
canceled_at: null,
|
|
current_period_start: 1677649423000,
|
|
current_period_end: 1680327823000,
|
|
},
|
|
]
|
|
features:
|
|
[
|
|
{
|
|
feature_id: "messages",
|
|
unlimited: false,
|
|
interval: "month",
|
|
balance: 80,
|
|
usage: 20,
|
|
included_usage: 100,
|
|
next_reset_at: 1680327823000,
|
|
},
|
|
]
|
|
schemas:
|
|
CustomerProduct:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
nullable: true
|
|
group:
|
|
type: string
|
|
nullable: true
|
|
status:
|
|
type: string
|
|
enum: [active, past_due, trialing]
|
|
started_at:
|
|
type: integer
|
|
format: int64
|
|
canceled_at:
|
|
type: integer
|
|
format: int64
|
|
nullable: true
|
|
current_period_start:
|
|
type: integer
|
|
format: int64
|
|
nullable: true
|
|
current_period_end:
|
|
type: integer
|
|
format: int64
|
|
nullable: true
|
|
CustomerFeature:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
unlimited:
|
|
type: boolean
|
|
interval:
|
|
type: string
|
|
enum: [month, year]
|
|
nullable: true
|
|
balance:
|
|
type: integer
|
|
nullable: true
|
|
usage:
|
|
type: integer
|
|
nullable: true
|
|
included_usage:
|
|
type: integer
|
|
nullable: true
|
|
next_reset_at:
|
|
type: integer
|
|
format: int64
|
|
nullable: true
|
|
Customer:
|
|
type: object
|
|
properties:
|
|
autumn_id:
|
|
type: string
|
|
description: Autumn's internal identifier for the customer
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
description: Timestamp of customer creation in milliseconds since epoch
|
|
env:
|
|
type: string
|
|
description: Environment the customer is in
|
|
enum: [production, sandbox]
|
|
id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
name:
|
|
type: string
|
|
description: Customer's name
|
|
email:
|
|
type: string
|
|
description: Customer's email address
|
|
fingerprint:
|
|
type: string
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
|
|
stripe_id:
|
|
type: string
|
|
description: Stripe customer ID
|
|
products:
|
|
type: array
|
|
description: List of products the customer has access to
|
|
items:
|
|
$ref: "#/components/schemas/CustomerProduct"
|
|
features:
|
|
type: array
|
|
description: List of features the customer has access to
|
|
items:
|
|
$ref: "#/components/schemas/CustomerFeature"
|
|
invoices:
|
|
type: array
|
|
description: Invoices for this customer (only included when expand=invoices)
|
|
items:
|
|
$ref: "#/components/schemas/Invoice"
|
|
Product:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the product
|
|
name:
|
|
type: string
|
|
description: Display name of the product
|
|
group:
|
|
type: string
|
|
description: Product grouping category
|
|
status:
|
|
type: string
|
|
enum: [active, past_due, trialing]
|
|
description: Current status of the product subscription.
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
description: Timestamp of product creation in milliseconds since epoch
|
|
canceled_at:
|
|
type: integer
|
|
format: int64
|
|
nullable: true
|
|
description: Timestamp of cancellation, if applicable
|
|
processor:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: Payment processor type
|
|
subscription_id:
|
|
type: string
|
|
nullable: true
|
|
description: Payment processor's subscription ID
|
|
prices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price amount in the default currency
|
|
interval:
|
|
type: string
|
|
enum: [month, year]
|
|
description: Billing interval for the price
|
|
Entitlement:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Unique identifier for the feature
|
|
interval:
|
|
type: string
|
|
description: Time interval for the entitlement
|
|
balance:
|
|
type: integer
|
|
nullable: true
|
|
description: Remaining balance of the entitlement
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether the entitlement has unlimited usage
|
|
used:
|
|
type: integer
|
|
description: Amount of the entitlement that has been used
|
|
Invoice:
|
|
type: object
|
|
properties:
|
|
product_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of product IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: Stripe invoice ID
|
|
status:
|
|
type: string
|
|
enum: [paid, unpaid, void]
|
|
description: Payment status of the invoice
|
|
total:
|
|
type: number
|
|
description: Total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: Currency code for the invoice
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
description: Timestamp of invoice creation in milliseconds since epoch
|
|
hosted_invoice_url:
|
|
type: string
|
|
format: uri
|
|
description: URL to view the hosted invoice page
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
publishableKeyAuthAttach:
|
|
type: http
|
|
scheme: bearer
|
|
description: You can use your Secret or Publishable key for this endpoint. Using your Publishable Key will always return a `checkout_url`. Using your Secret Key allows you to handle payments automatically (eg, for plan upgrades).
|
|
secretKeyAuth:
|
|
type: http
|
|
scheme: bearer
|
|
description: Your secret key must be used as the Bearer token for this endpoint.
|
|
publishableKeyAuthEntitled:
|
|
type: http
|
|
scheme: bearer
|
|
description: You can use your Secret or Publishable key for this endpoint. To include usage event tracking however, you must use your Secret key.
|