333 lines
11 KiB
YAML
333 lines
11 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/batch
|
|
|
|
security:
|
|
- secretKeyAuth: []
|
|
|
|
paths:
|
|
/customers:
|
|
post:
|
|
summary: Batch retrieve customers
|
|
description: Retrieve a paginated list of customers with their associated products and entitlements
|
|
operationId: batchGetCustomers
|
|
tags:
|
|
- Batch Operations
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- limit
|
|
properties:
|
|
limit:
|
|
type: integer
|
|
description: Number of customers to retrieve (Must be between 10 and 100)
|
|
example: 100
|
|
offset:
|
|
type: integer
|
|
default: 0
|
|
description: Number of customers to skip for pagination
|
|
example: 100
|
|
statuses:
|
|
type: array
|
|
default: ["active"]
|
|
items:
|
|
type: string
|
|
enum:
|
|
- scheduled
|
|
- active
|
|
- past_due
|
|
- expired
|
|
- unknown
|
|
- trialing
|
|
description: Filter customers by product status
|
|
example: ["expired", "past_due"]
|
|
examples:
|
|
basic:
|
|
summary: Basic request
|
|
value:
|
|
limit: 50
|
|
with-filters:
|
|
summary: With status filters
|
|
value:
|
|
limit: 100
|
|
offset: 100
|
|
statuses: ["expired", "past_due"]
|
|
responses:
|
|
"200":
|
|
description: Successful response with paginated customer list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- list
|
|
- total
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Customer"
|
|
description: Array of customer objects
|
|
total:
|
|
type: integer
|
|
description: Total number of customers in the result set
|
|
example: 25
|
|
examples:
|
|
success:
|
|
summary: Successful response
|
|
value:
|
|
list:
|
|
- id: "John Doe"
|
|
created_at: 1756301935674
|
|
name: "John Doe"
|
|
email: "john@example.com"
|
|
fingerprint: null
|
|
stripe_id: null
|
|
env: "sandbox"
|
|
products:
|
|
- id: "free"
|
|
name: "free"
|
|
group: null
|
|
status: "active"
|
|
canceled_at: null
|
|
started_at: 1756310054931
|
|
is_default: true
|
|
is_add_on: false
|
|
version: 2
|
|
items:
|
|
- type: "feature"
|
|
feature_id: "message"
|
|
feature_type: "single_use"
|
|
feature:
|
|
id: "message"
|
|
name: "Send Message"
|
|
type: "single_use"
|
|
display:
|
|
singular: "message"
|
|
plural: "messages"
|
|
included_usage: 1000
|
|
interval: "month"
|
|
interval_count: 1
|
|
reset_usage_when_enabled: true
|
|
entity_feature_id: null
|
|
features:
|
|
message:
|
|
id: "message"
|
|
name: "Send Message"
|
|
type: "single_use"
|
|
unlimited: false
|
|
balance: 1000
|
|
usage: 0
|
|
included_usage: 1000
|
|
next_reset_at: 1758980335931
|
|
interval: "month"
|
|
interval_count: 1
|
|
overage_allowed: false
|
|
metadata: {}
|
|
- id: "John Doe"
|
|
created_at: 1756301935674
|
|
name: "John Doe"
|
|
email: "john@example.com"
|
|
fingerprint: null
|
|
stripe_id: null
|
|
env: "sandbox"
|
|
products:
|
|
- id: "free"
|
|
name: "free"
|
|
group: null
|
|
status: "active"
|
|
canceled_at: null
|
|
started_at: 1756310054931
|
|
is_default: true
|
|
is_add_on: false
|
|
version: 2
|
|
items:
|
|
- type: "feature"
|
|
feature_id: "message"
|
|
feature_type: "single_use"
|
|
feature:
|
|
id: "message"
|
|
name: "Send Message"
|
|
type: "single_use"
|
|
display:
|
|
singular: "message"
|
|
plural: "messages"
|
|
included_usage: 1000
|
|
interval: "month"
|
|
interval_count: 1
|
|
reset_usage_when_enabled: true
|
|
entity_feature_id: null
|
|
features:
|
|
message:
|
|
id: "message"
|
|
name: "Send Message"
|
|
type: "single_use"
|
|
unlimited: false
|
|
balance: 1000
|
|
usage: 0
|
|
included_usage: 1000
|
|
next_reset_at: 1758980335931
|
|
interval: "month"
|
|
interval_count: 1
|
|
overage_allowed: false
|
|
metadata: {}
|
|
total: 1
|
|
|
|
components:
|
|
securitySchemes:
|
|
secretKeyAuth:
|
|
type: http
|
|
scheme: bearer
|
|
description: Use your Autumn Secret Key as the Bearer token.
|
|
|
|
schemas:
|
|
Customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Customer ID provided by user
|
|
example: "cus_123"
|
|
name:
|
|
type: string
|
|
description: Customer name
|
|
example: "John Doe"
|
|
email:
|
|
type: string
|
|
description: Customer email address
|
|
example: "john@example.com"
|
|
fingerprint:
|
|
type: string
|
|
description: Customer fingerprint for identification
|
|
example: "fp_abc123"
|
|
internal_id:
|
|
type: string
|
|
description: Internal Autumn customer ID
|
|
example: "int_123"
|
|
created_at:
|
|
type: integer
|
|
description: Customer creation timestamp (Unix timestamp in milliseconds)
|
|
example: 1640995200000
|
|
metadata:
|
|
type: object
|
|
description: Additional customer metadata
|
|
additionalProperties: true
|
|
example: {}
|
|
customer_products:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CustomerProduct"
|
|
description: Associated customer products
|
|
entitlements:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CustomerEntitlement"
|
|
description: Customer entitlements and balances
|
|
|
|
CustomerProduct:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Customer product ID
|
|
product_id:
|
|
type: string
|
|
description: Associated product ID
|
|
status:
|
|
type: string
|
|
enum:
|
|
- scheduled
|
|
- active
|
|
- past_due
|
|
- expired
|
|
- unknown
|
|
- trialing
|
|
description: Product status
|
|
created_at:
|
|
type: integer
|
|
description: Product creation timestamp
|
|
starts_at:
|
|
type: integer
|
|
description: Product start timestamp
|
|
canceled_at:
|
|
type: integer
|
|
nullable: true
|
|
description: Product cancellation timestamp
|
|
ended_at:
|
|
type: integer
|
|
nullable: true
|
|
description: Product end timestamp
|
|
trial_ends_at:
|
|
type: integer
|
|
nullable: true
|
|
description: Trial end timestamp
|
|
quantity:
|
|
type: integer
|
|
description: Product quantity
|
|
default: 1
|
|
collection_method:
|
|
type: string
|
|
enum:
|
|
- charge_automatically
|
|
- send_invoice
|
|
description: Payment collection method
|
|
|
|
CustomerEntitlement:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Entitlement ID
|
|
feature_id:
|
|
type: string
|
|
description: Associated feature ID
|
|
balance:
|
|
type: number
|
|
description: Current balance
|
|
adjustment:
|
|
type: number
|
|
description: Balance adjustment
|
|
next_reset_at:
|
|
type: integer
|
|
nullable: true
|
|
description: Next balance reset timestamp
|
|
created_at:
|
|
type: integer
|
|
description: Entitlement creation timestamp
|
|
|
|
Error:
|
|
type: object
|
|
required:
|
|
- error
|
|
properties:
|
|
error:
|
|
type: object
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: Error code
|
|
enum:
|
|
- invalid_inputs
|
|
- invalid_request
|
|
- no_secret_key
|
|
- invalid_secret_key
|
|
- customers_not_found
|
|
- internal_error
|
|
message:
|
|
type: string
|
|
description: Human-readable error message
|