1340 lines
47 KiB
YAML
1340 lines
47 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:
|
|
- secretKeyAuth: []
|
|
|
|
paths:
|
|
/checkout:
|
|
post:
|
|
security:
|
|
- secretKeyAuth: []
|
|
description: Returns a Stripe Checkout URL for the customer to make a payment, or returns payment confirmation information.
|
|
requestBody:
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- customer_id
|
|
- product_id
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
product_id:
|
|
type: string
|
|
description: Product ID, set when creating the product in the Autumn dashboard
|
|
product_ids:
|
|
type: array
|
|
description: List of product IDs to attach to the customer in the same subscription or transaction
|
|
items:
|
|
type: string
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after the purchase is successful
|
|
options:
|
|
type: array
|
|
description: Pass in quantities for prepaid features.
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Feature ID of the feature that will be affected by the options.
|
|
quantity:
|
|
type: integer
|
|
description: Quantity of the feature (eg number of seats) to be purchased. Required if billing is in-advance usage-based.
|
|
reward:
|
|
type: string
|
|
description: An Autumn promo_code or reward_id to apply at checkout.
|
|
entity_id:
|
|
type: string
|
|
description: If using [entities](/features/feature-entities), the entity to attach the product to.
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
checkout_session_params:
|
|
type: object
|
|
description: Additional parameters to pass onto Stripe when creating the checkout session.
|
|
x-code-samples:
|
|
- lang: typescript
|
|
label: required
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js'
|
|
|
|
const response = await autumn.checkout({
|
|
customer_id: 'user_123',
|
|
product_id: 'pro'
|
|
})
|
|
- lang: typescript
|
|
label: with customer_data
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.checkout({
|
|
customer_id: 'user_123',
|
|
product_id: 'pro',
|
|
customer_data: {
|
|
name: 'John Yeo',
|
|
email: 'john@example.com'
|
|
}
|
|
});
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/checkout' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"product_id": "pro"
|
|
}'
|
|
- lang: python
|
|
label: required
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.checkout(
|
|
customer_id='user_123',
|
|
product_id='pro'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: with customer_data
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn, CustomerData
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.checkout(
|
|
customer_id='user_123',
|
|
product_id='pro',
|
|
customer_data=CustomerData(
|
|
name='John Yeo',
|
|
email='john@example.com'
|
|
)
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: " "
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
checkout url:
|
|
value:
|
|
url: "https://checkout.stripe.com/c/pay/cs_test_b1aiNVtSaxIymaUwIgzyDqxsX9TryoFzm8uS0nhncxN6TXFKCydjB9waEk#fid2cGd2ZndsdXFsamtQa2x0cGBrYHZ2QGtkZ2lgYSc%2FY2RpdmApJ2R1bE5gfCc%2FJ3VuWnFgdnFaMDRVajE2YUJNal9QRHVdXWFUVU90T0xNN3NUSXRdXWNqbEw9RGd2QlF9TkhdSU9VU29uSFFRSzJzVUJoVzFxalFhZzw0QmBUUXI9ckZDbGNEQ39nM1N9aGM1NWN2cTN0QWtrJyknY3dqaFZgd3Ngdyc%2FcXdwYCknaWR8anBxUXx1YCc%2FJ2hwaXFsWmxxYGgnKSdga2RnaWBVaWRmYG1qaWFgd3YnP3F3cGB4JSUl"
|
|
customer_id: "b"
|
|
lines: []
|
|
product:
|
|
id: "pro"
|
|
name: "Pro"
|
|
group: null
|
|
env: "sandbox"
|
|
is_add_on: false
|
|
is_default: false
|
|
version: 2
|
|
created_at: 1753805339212
|
|
items:
|
|
- type: "price"
|
|
feature_id: null
|
|
feature: null
|
|
interval: "month"
|
|
price: 20
|
|
- type: "priced_feature"
|
|
feature_id: "messages"
|
|
feature_type: "single_use"
|
|
feature:
|
|
id: "messages"
|
|
name: "Messages"
|
|
type: "single_use"
|
|
display:
|
|
singular: "message"
|
|
plural: "messages"
|
|
included_usage: 100
|
|
interval: "month"
|
|
price: 0.1
|
|
usage_model: "pay_per_use"
|
|
billing_units: 1
|
|
reset_usage_when_enabled: false
|
|
entity_feature_id: null
|
|
free_trial: null
|
|
base_variant_id: null
|
|
scenario: "new"
|
|
properties:
|
|
is_free: false
|
|
is_one_off: false
|
|
interval_group: "month"
|
|
has_trial: false
|
|
updateable: false
|
|
upgrades and downgrades:
|
|
value:
|
|
customer_id: "a"
|
|
lines:
|
|
- description: "Unused Pro - $20 / month (from 29 Jul 2025)"
|
|
amount: -19.92096809289128
|
|
item:
|
|
type: "price"
|
|
feature_id: null
|
|
feature: null
|
|
interval: "month"
|
|
price: 20
|
|
display:
|
|
primary_text: "$20"
|
|
secondary_text: "per month"
|
|
- description: "Pro - 200 messages"
|
|
amount: 10
|
|
item:
|
|
type: "priced_feature"
|
|
feature_id: "messages"
|
|
feature_type: "single_use"
|
|
feature:
|
|
id: "messages"
|
|
name: "Messages"
|
|
type: "single_use"
|
|
display:
|
|
singular: "message"
|
|
plural: "messages"
|
|
included_usage: 100
|
|
interval: "month"
|
|
price: 0.1
|
|
usage_model: "pay_per_use"
|
|
billing_units: 1
|
|
reset_usage_when_enabled: false
|
|
entity_feature_id: null
|
|
display:
|
|
primary_text: "100 message"
|
|
secondary_text: "then $0.1 per message"
|
|
- description: "Ultra - $100 / month (from 29 Jul 2025)"
|
|
amount: 99.60484046445639
|
|
item:
|
|
type: "price"
|
|
feature_id: null
|
|
feature: null
|
|
interval: "month"
|
|
price: 100
|
|
display:
|
|
primary_text: "$100"
|
|
secondary_text: "per month"
|
|
product:
|
|
id: "ultra"
|
|
name: "Ultra"
|
|
group: null
|
|
env: "sandbox"
|
|
is_add_on: false
|
|
is_default: false
|
|
version: 1
|
|
created_at: 1753816049300
|
|
items:
|
|
- type: "price"
|
|
feature_id: null
|
|
feature: null
|
|
interval: "month"
|
|
price: 100
|
|
display:
|
|
primary_text: "$100"
|
|
secondary_text: "per month"
|
|
- type: "feature"
|
|
feature_id: "messages"
|
|
feature_type: "single_use"
|
|
feature:
|
|
id: "messages"
|
|
name: "Messages"
|
|
type: "single_use"
|
|
display:
|
|
singular: "message"
|
|
plural: "messages"
|
|
included_usage: 100
|
|
interval: "month"
|
|
reset_usage_when_enabled: true
|
|
entity_feature_id: null
|
|
display:
|
|
primary_text: "100 message"
|
|
free_trial: null
|
|
base_variant_id: null
|
|
scenario: "upgrade"
|
|
properties:
|
|
is_free: false
|
|
is_one_off: false
|
|
interval_group: "month"
|
|
has_trial: false
|
|
updateable: false
|
|
current_product:
|
|
id: "pro"
|
|
name: "Pro"
|
|
group: null
|
|
env: "sandbox"
|
|
is_add_on: false
|
|
is_default: false
|
|
version: 2
|
|
created_at: 1753805339212
|
|
items:
|
|
- type: "price"
|
|
feature_id: null
|
|
feature: null
|
|
interval: "month"
|
|
price: 20
|
|
display:
|
|
primary_text: "$20"
|
|
secondary_text: "per month"
|
|
- type: "priced_feature"
|
|
feature_id: "messages"
|
|
feature_type: "single_use"
|
|
feature:
|
|
id: "messages"
|
|
name: "Messages"
|
|
type: "single_use"
|
|
display:
|
|
singular: "message"
|
|
plural: "messages"
|
|
included_usage: 100
|
|
interval: "month"
|
|
price: 0.1
|
|
usage_model: "pay_per_use"
|
|
billing_units: 1
|
|
reset_usage_when_enabled: false
|
|
entity_feature_id: null
|
|
display:
|
|
primary_text: "100 message"
|
|
secondary_text: "then $0.1 per message"
|
|
free_trial: null
|
|
base_variant_id: null
|
|
scenario: "new"
|
|
properties:
|
|
is_free: false
|
|
is_one_off: false
|
|
interval_group: "month"
|
|
has_trial: false
|
|
updateable: false
|
|
total: 89.68387237156512
|
|
currency: "USD"
|
|
next_cycle:
|
|
starts_at: 1756483882000
|
|
total: 100
|
|
options: []
|
|
has_prorations: true
|
|
|
|
/attach:
|
|
post:
|
|
security:
|
|
- secretKeyAuth: []
|
|
description: Enables a product and handles a payment if the customer's card is already on file.
|
|
requestBody:
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- customer_id
|
|
- product_id
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
product_id:
|
|
type: string
|
|
description: Product ID, set when creating the product in the Autumn dashboard
|
|
product_ids:
|
|
type: array
|
|
description: List of product IDs to attach to the customer in the same subscription or transaction
|
|
items:
|
|
type: string
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after the purchase is successful
|
|
options:
|
|
type: array
|
|
description: Pass in quantities for prepaid features.
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Feature ID of the feature that will be affected by the options.
|
|
quantity:
|
|
type: integer
|
|
description: Quantity of the feature (eg number of seats) to be purchased. Required if billing is in-advance usage-based.
|
|
reward:
|
|
type: string
|
|
description: An Autumn promo_code or reward_id to apply at checkout.
|
|
entity_id:
|
|
type: string
|
|
description: If using [entities](/features/feature-entities), the entity to attach the product to.
|
|
force_checkout:
|
|
type: boolean
|
|
default: false
|
|
description: Always return a Stripe Checkout URL, even if the customer's card is already on file.
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
metadata:
|
|
type: object
|
|
description: Additional metadata to pass onto Stripe.
|
|
checkout_session_params:
|
|
type: object
|
|
description: Additional parameters to pass onto Stripe when creating the checkout session.
|
|
x-code-samples:
|
|
- lang: typescript
|
|
label: required
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js'
|
|
|
|
const response = await autumn.attach({
|
|
customer_id: 'user_123',
|
|
product_id: 'pro'
|
|
})
|
|
- lang: typescript
|
|
label: with customer_data
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.attach({
|
|
customer_id: 'user_123',
|
|
product_id: 'pro',
|
|
customer_data: {
|
|
name: 'John Yeo',
|
|
email: 'john@example.com'
|
|
}
|
|
});
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/attach' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"product_id": "pro"
|
|
}'
|
|
- lang: python
|
|
label: required
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.attach(
|
|
customer_id='user_123',
|
|
product_id='pro'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: with customer_data
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn, CustomerData
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.attach(
|
|
customer_id='user_123',
|
|
product_id='pro',
|
|
customer_data=CustomerData(
|
|
name='John Yeo',
|
|
email='john@example.com'
|
|
)
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: Customer attached
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
checkout_url:
|
|
type: string
|
|
description: URL to the Stripe checkout page. Only present if payment is required.
|
|
success:
|
|
type: boolean
|
|
description: Indicates if the product change was successful. Only present if payment is not required.
|
|
message:
|
|
type: string
|
|
description: Description of the action taken
|
|
examples:
|
|
upgrades and downgrades:
|
|
value:
|
|
customer_id: "a"
|
|
product_ids:
|
|
- "pro"
|
|
code: "updated_product_successfully"
|
|
message: "Successfully updated product"
|
|
|
|
/customers/{customer_id}/billing_portal:
|
|
post:
|
|
description: Get the customer's Stripe billing portal URL, so they can manage their subscription and see invoice history.
|
|
parameters:
|
|
- name: customer_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: ID which you provided when creating the customer
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
return_url:
|
|
type: string
|
|
description: URL to return to after the customer is finished in the billing portal
|
|
x-code-samples:
|
|
- lang: typescript
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.customers.billingPortal('user_123', {
|
|
return_url: 'https://example.com/account'
|
|
});
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/customers/user_123/billing_portal' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"return_url": "https://example.com/account"
|
|
}'
|
|
- lang: python
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.customers.get_billing_portal(
|
|
"user_123", returl_url="https://example.com/account"
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
url:
|
|
type: string
|
|
description: URL to access the customer's billing portal
|
|
example:
|
|
url: https://billing.stripe.com/session/<hash>
|
|
|
|
/track:
|
|
post:
|
|
description: Track a usage event in Autumn
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
allOf:
|
|
- properties:
|
|
customer_id:
|
|
type: string
|
|
description: ID which you provided when creating the customer
|
|
- $ref: "#/components/schemas/EventData"
|
|
- properties:
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
x-code-samples:
|
|
- lang: typescript
|
|
label: with value
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
await autumn.track({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages',
|
|
value: 3
|
|
});
|
|
|
|
- lang: typescript
|
|
label: single event
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
await autumn.track({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages'
|
|
});
|
|
|
|
- lang: typescript
|
|
label: with customer data
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
await autumn.track({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages',
|
|
value: 12,
|
|
customer_data: {
|
|
name: 'John Yeo',
|
|
email: 'john@useautumn.com'
|
|
}
|
|
});
|
|
|
|
- lang: typescript
|
|
label: with event name
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
await autumn.track({
|
|
customer_id: 'user_123',
|
|
event_name: 'mobile_messages',
|
|
value: 12
|
|
});
|
|
|
|
- lang: bash
|
|
label: with value
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/track' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": "messages",
|
|
"value": 3
|
|
}'
|
|
|
|
- lang: bash
|
|
label: single event
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/track' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": "messages"
|
|
}'
|
|
- lang: python
|
|
label: with value
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
await autumn.track(
|
|
customer_id='user_123',
|
|
feature_id='messages',
|
|
value=3
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: single event
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
await autumn.track(
|
|
customer_id='user_123',
|
|
feature_id='messages',
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: with customer data
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn, CustomerData
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
await autumn.track(
|
|
customer_id='user_123',
|
|
feature_id='messages',
|
|
value=12,
|
|
customer_data=CustomerData(
|
|
name='John Yeo',
|
|
email='john@example.com'
|
|
)
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: with event name
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
await autumn.track(
|
|
customer_id='user_123',
|
|
event_name='mobile_messages',
|
|
value=12
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the event
|
|
code:
|
|
type: string
|
|
description: Status code indicating the result of sending the event
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature being tracked
|
|
example:
|
|
id: "evt_2w5dzidzFD1cESxOGnn9frVuVcm"
|
|
code: "event_received"
|
|
customer_id: "user_123"
|
|
feature_id: "messages"
|
|
|
|
/check:
|
|
post:
|
|
security:
|
|
- secretKeyAuth: []
|
|
description: Check if a customer has access to a feature or product
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- customer_id
|
|
properties:
|
|
product_id:
|
|
type: string
|
|
description: ID of the product to check access to. Required if `feature_id` is not provided.
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature to check access to. Required if `product_id` is not provided.
|
|
customer_id:
|
|
type: string
|
|
description: ID which you provided when creating the customer
|
|
required_balance:
|
|
type: integer
|
|
default: 1
|
|
description: If you know the amount of the feature the end user is consuming in advance. If their balance is below this quantity, `allowed` will be `false`.
|
|
send_event:
|
|
type: boolean
|
|
description: If true, a usage event will be recorded together with checking access. The `required_balance` field will be used as the usage `value`.
|
|
with_preview:
|
|
type: boolean
|
|
default: false
|
|
description: If true, the response will include a `preview` object, which can be used to display [information](/quickstart/ui-components) such as a paywall or upgrade confirmation.
|
|
entity_id:
|
|
type: string
|
|
description: If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to check access for.
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
x-code-samples:
|
|
- lang: typescript
|
|
label: required
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.check({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages'
|
|
});
|
|
|
|
- lang: typescript
|
|
label: with event
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.check({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages',
|
|
required_balance: 12,
|
|
send_event: true
|
|
});
|
|
|
|
- lang: typescript
|
|
label: with customer data
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.check({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages',
|
|
customer_data: {
|
|
name: 'John Yeo',
|
|
email: 'john@useautumn.com'
|
|
}
|
|
});
|
|
|
|
- lang: curl
|
|
label: required
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/check' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": "messages"
|
|
}'
|
|
|
|
- lang: curl
|
|
label: with event
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/check' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": "messages",
|
|
"required_balance": 12,
|
|
"send_event": true
|
|
}'
|
|
|
|
- lang: curl
|
|
label: with customer data
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/check' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": "messages",
|
|
"customer_data": {
|
|
"name": "John Yeo",
|
|
"email": "john@useautumn.com"
|
|
}
|
|
}'
|
|
- lang: python
|
|
label: required
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
response = await autumn.check(
|
|
customer_id='user_123',
|
|
feature_id='messages'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: with event
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
response = await autumn.check(
|
|
customer_id='user_123',
|
|
feature_id='messages',
|
|
required_balance=12,
|
|
send_event=True
|
|
)
|
|
|
|
asyncio.run(main())
|
|
|
|
- lang: python
|
|
label: with customer_data
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn, CustomerData
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
response = await autumn.check(
|
|
customer_id='user_123',
|
|
feature_id='messages',
|
|
customer_data=CustomerData(
|
|
name='John Yeo',
|
|
email='john@useautumn.com'
|
|
)
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
allowed:
|
|
type: boolean
|
|
description: Whether the customer has access to the feature or product
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature being checked
|
|
code:
|
|
type: string
|
|
description: Status code indicating the result of the check
|
|
balance:
|
|
type: object
|
|
description: Balances of the associated feature or credit system
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature
|
|
required_balance:
|
|
type: integer
|
|
description: Required amount of the feature
|
|
balance:
|
|
type: integer
|
|
description: Current balance of the feature
|
|
feature_preview:
|
|
type: object
|
|
description: Information about the feature, used to display information such as a paywall. Returned if check is called with a `feature_id` and `with_preview` is true.
|
|
properties:
|
|
title:
|
|
type: string
|
|
description: Title of the preview message
|
|
message:
|
|
type: string
|
|
description: Message to display to the user
|
|
scenario:
|
|
type: string
|
|
enum:
|
|
- usage_limit
|
|
- feature_flag
|
|
description: The scenario of the feature preview
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature
|
|
feature_name:
|
|
type: string
|
|
description: Name of the feature
|
|
products:
|
|
type: array
|
|
description: List of available products that include this feature
|
|
upgrade_product_id:
|
|
type: string
|
|
description: Next available product tier to upgrade to
|
|
product_preview:
|
|
type: object
|
|
description: Information about the product, used to display information such as an upgrade confirmation. Returned if check is called with a `product_id` and `with_preview` is true.
|
|
properties:
|
|
title:
|
|
type: string
|
|
description: Title of the preview message
|
|
message:
|
|
type: string
|
|
description: Message to display to the user
|
|
scenario:
|
|
type: string
|
|
enum:
|
|
- upgrade
|
|
- downgrade
|
|
- cancel
|
|
- renew
|
|
- scheduled
|
|
- active
|
|
description: The scenario of the product preview
|
|
product_id:
|
|
type: string
|
|
description: ID of the product
|
|
product_name:
|
|
type: string
|
|
description: Name of the product
|
|
recurring:
|
|
type: boolean
|
|
description: Whether the product is recurring
|
|
next_cycle_at:
|
|
type: integer
|
|
description: Timestamp of the next billing cycle
|
|
current_product_name:
|
|
type: string
|
|
description: Name of the current product
|
|
items:
|
|
type: array
|
|
description: List of items in the preview
|
|
items:
|
|
type: object
|
|
properties:
|
|
price:
|
|
type: string
|
|
description: Price of the item ($8)
|
|
description:
|
|
type: string
|
|
description: Description of the item (Eg, time used on Pro plan)
|
|
options:
|
|
type: array
|
|
description: List of available options required to attach the product (eg, quantity of seats)
|
|
due_today:
|
|
type: object
|
|
description: Amount due today
|
|
properties:
|
|
price:
|
|
type: number
|
|
description: Price amount
|
|
currency:
|
|
type: string
|
|
description: Currency code
|
|
due_next_cycle:
|
|
type: object
|
|
description: Amount due in next cycle
|
|
properties:
|
|
price:
|
|
type: number
|
|
description: Price amount
|
|
currency:
|
|
type: string
|
|
description: Currency code
|
|
example:
|
|
customer_id: "user_123"
|
|
feature_id: "messages"
|
|
code: "feature_found"
|
|
allowed: true
|
|
balance: { balance: 100, required_balance: 12 }
|
|
|
|
/query:
|
|
post:
|
|
security:
|
|
- secretKeyAuth: []
|
|
description: Query usage data for specific features over a time range
|
|
requestBody:
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
feature_id:
|
|
oneOf:
|
|
- type: string
|
|
- type: array
|
|
items:
|
|
type: string
|
|
description: Feature ID or array of feature IDs to query usage for
|
|
range:
|
|
type: string
|
|
enum: ["24h", "7d", "30d", "90d", "last_cycle"]
|
|
description: Time range for the query. Defaults to "30d" if not provided. `last_cycle` returns usage since the last billing cycle.
|
|
x-code-samples:
|
|
- lang: typescript
|
|
label: single feature
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js'
|
|
|
|
const response = await autumn.query({
|
|
customer_id: 'user_123',
|
|
feature_id: 'messages',
|
|
range: '30d'
|
|
})
|
|
- lang: typescript
|
|
label: multiple features
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js'
|
|
|
|
const response = await autumn.query({
|
|
customer_id: 'user_123',
|
|
feature_id: ['credits', 'messages'],
|
|
range: '7d'
|
|
})
|
|
- lang: curl
|
|
label: single feature
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/query' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": "messages",
|
|
"range": "30d"
|
|
}'
|
|
- lang: curl
|
|
label: multiple features
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/query' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"feature_id": ["credits", "messages"],
|
|
"range": "7d"
|
|
}'
|
|
- lang: python
|
|
label: single feature
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.query(
|
|
customer_id='user_123',
|
|
feature_id='messages',
|
|
range='30d'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: multiple features
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn("am_sk_1234567890")
|
|
|
|
async def main():
|
|
response = await autumn.query(
|
|
customer_id='user_123',
|
|
feature_id=['credits', 'messages'],
|
|
range='7d'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: Usage data for the specified features
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
description: List of usage data points for each time period
|
|
items:
|
|
type: object
|
|
properties:
|
|
period:
|
|
type: integer
|
|
description: Unix timestamp in milliseconds representing start of period
|
|
additionalProperties:
|
|
type: integer
|
|
description: Usage amount for each feature_id in the period
|
|
examples:
|
|
single feature:
|
|
value:
|
|
list:
|
|
- period: 1672531200000
|
|
messages: 45
|
|
- period: 1672617600000
|
|
messages: 32
|
|
- period: 1672704000000
|
|
messages: 18
|
|
multiple features:
|
|
value:
|
|
list:
|
|
- period: 1672531200000
|
|
credits: 20
|
|
messages: 45
|
|
- period: 1672617600000
|
|
credits: 15
|
|
messages: 32
|
|
- period: 1672704000000
|
|
credits: 30
|
|
messages: 18
|
|
|
|
/cancel:
|
|
post:
|
|
security:
|
|
- secretKeyAuth: []
|
|
description: Cancel a customer's subscription or product attachment
|
|
requestBody:
|
|
description: ""
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- customer_id
|
|
- product_id
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
product_id:
|
|
type: string
|
|
description: Product ID to cancel for the customer
|
|
entity_id:
|
|
type: string
|
|
description: If using [entities](/features/feature-entities), the entity to cancel the product for.
|
|
cancel_immediately:
|
|
type: boolean
|
|
description: Whether to cancel the product immediately. If false, the product will be cancelled at the end of the billing cycle.
|
|
x-code-samples:
|
|
- lang: typescript
|
|
label: required
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js'
|
|
|
|
const response = await autumn.cancel({
|
|
customer_id: 'user_123',
|
|
product_id: 'lite'
|
|
})
|
|
- lang: typescript
|
|
label: with entity
|
|
source: |
|
|
import { Autumn as autumn } from 'autumn-js';
|
|
|
|
const response = await autumn.cancel({
|
|
customer_id: 'user_123',
|
|
product_id: 'lite',
|
|
entity_id: '1'
|
|
});
|
|
- lang: curl
|
|
label: required
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/cancel' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"product_id": "lite"
|
|
}'
|
|
- lang: curl
|
|
label: with entity
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/cancel' \
|
|
-H 'Authorization: Bearer am_sk_1234567890' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"customer_id": "user_123",
|
|
"product_id": "lite",
|
|
"entity_id": "1"
|
|
}'
|
|
- lang: python
|
|
label: required
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
response = await autumn.products.cancel(
|
|
customer_id='user_123',
|
|
product_id='lite'
|
|
)
|
|
|
|
asyncio.run(main())
|
|
- lang: python
|
|
label: with entity
|
|
source: |
|
|
import asyncio
|
|
from autumn import Autumn
|
|
|
|
autumn = Autumn('am_sk_1234567890')
|
|
|
|
async def main():
|
|
response = await autumn.products.cancel(
|
|
customer_id='user_123',
|
|
product_id='lite',
|
|
entity_id='1',
|
|
)
|
|
|
|
asyncio.run(main())
|
|
responses:
|
|
"200":
|
|
description: Product cancelled successfully
|
|
|
|
components:
|
|
schemas:
|
|
CustomerData:
|
|
type: object
|
|
description: Additional customer properties. These will be used if the customer's properties are not already set.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Name of the customer
|
|
email:
|
|
type: string
|
|
description: Email of the customer
|
|
fingerprint:
|
|
type: string
|
|
description: Unique fingerprint of the customer, used to prevent free trial abuse (eg serial_number, device_id, etc)
|
|
|
|
EventData:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature to track usage for.
|
|
value:
|
|
type: integer
|
|
default: 1
|
|
description: How much usage should be deducted from the balance. Default is 1.
|
|
entity_id:
|
|
type: string
|
|
description: If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to track usage for.
|
|
event_name:
|
|
type: string
|
|
description: An [event name](/features/tracking-usage#using-event-names) can be used in place of `feature_id`. This can be used if multiple features are tracked in the same event.
|
|
idempotency_key:
|
|
type: string
|
|
description: Unique identifier for the event. If the an event with the same key is sent multiple times, any subsequent events will be ignored and return an error.
|
|
properties:
|
|
type: object
|
|
description: Event properties that you can define.
|
|
|
|
Error:
|
|
required:
|
|
- error
|
|
- message
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: integer
|
|
format: int32
|
|
message:
|
|
type: string
|
|
|
|
securitySchemes:
|
|
secretKeyAuth:
|
|
type: http
|
|
scheme: bearer
|
|
description: Use your Autumn Secret Key as the Bearer token.
|