Candle

api

introduction

Welcome to the API documentation! Our API conforms to the REST architectural style, emphasizing principles like statelessness and a uniform interface for resource interaction.

The API communicates using application/json format, ensuring compatibility with various programming languages and platforms, and all interactions are secured via HTTPS (Hypertext Transfer Protocol Secure) to maintain data confidentiality and integrity.

Each marketplace created is issued a unique API key. Depending on the mode (live or test) in which the platform was created, the scope of the API key will be restricted to that specific mode. API keys must be passed in the request headers as Bearer tokens for authentication and authorization purposes.

To facilitate a smooth developer experience, we strive to maintain consistency and backward compatibility across different API versions, helping ensure seamless transitions and minimizing disruptions to existing integrations.

You can access the API using the base URL https://api.candle.so/:version , which provides a clear and standardized entry point for making API requests. Be sure to specify the correct version in the URL and include your API key in the request headers to successfully interact with the API.

authentication

Authentication for our API is conducted using API keys, which are passed in the request headers for each API call. Depending on whether your platform is in test mode or live mode, the corresponding API key should be included in the Authorization header as a Bearer token.

Header Format

Ensure that the Authorization header follows this format:

  • Test Mode: Authorization: Bearer cndl_test_xxx

  • Live Mode: Authorization: Bearer cndl_live_xxx

date formats

Dates within the API are consistently formatted using the UTC ISO standard (YYYY-MM-DDTHH:MM:SSZ), ensuring uniformity and ease of interpretation across different systems and time zones

Internally, dates are stored in UTC ISO format, having been converted from the user's preferred timezone to maintain consistency and prevent discrepancies in date representations

For converting dates from UTC to a user's preferred timezone, developers can utilize the /calendar/localtime?date= endpoint, which provides the functionality to adjust the timestamp accordingly

error handling

Error handling within the API relies on standard HTTP response codes, allowing developers to identify the nature of the error encountered during API interactions

In addition to HTTP response codes, errors received from third-party integrations, such as Stripe, are passed along to provide detailed insights into the root cause of issues related to external services

Guides
Coming Soon, guides to help you get started

Auth

The auth resource in our API handles authentication and authorization processes, ensuring secure access to the platform. Users can authenticate using their credentials to receive a unique token, which is required for all subsequent API requests. This token verifies the user's identity and permissions, allowing access to various resources and functionalities based on their role and subscription status. Additionally, the auth resource supports features like token refresh, ensuring uninterrupted access without frequent logins, and role-based access control, providing fine-grained permission management for different user roles such as owner, admin, editor, and member. This robust authentication system guarantees that only authorized users can access and interact with the marketplace, maintaining the security and integrity of the platform.

Was this helful?
Yes
No

Endpoints

POST
/auth/otp/email
POST
/auth/otp/verify
POST
/auth/session/refresh

Request OTP via email

Passwordless authentication. Use this endpoint to send an OTP to the user's email address.

Parameters:

No parameters
POST
/auth/otp/email
The Response
{}

Verify OTP

Passwordless authentication. Use this endpoint to verify an OTP sent to the user's email address.

Parameters:

No parameters
POST
/auth/otp/verify
The Response
{}

Refresh session

This endpoint is used to refresh the session. It can be used to extend the session's expiry time.

Parameters:

No parameters
POST
/auth/session/refresh
The Response
{}

Platforms

The platforms resource in our API allows users to interact with various aspects of their marketplace platform. Whether you need to retrieve platform details by domain or ID, upload a platform logo, or modify platform information, this resource provides the necessary endpoints. Additionally, you can list platform keys, check community membership, and manage platform-specific settings. These functionalities ensure that users have comprehensive control and flexibility in managing their marketplace platforms, enhancing the overall user experience and operational efficiency.

Was this helful?
Yes
No

Endpoints

GET
/platforms/domains/:domain
GET
/platforms
POST
/platforms/:id/image
PUT
/platforms/:id
GET
/platforms/community/user/:user_id

The Object

Attribute
Description
id
string
The unique identifier of the platform
mode
string
The mode of the platform, either 'test' or 'live'
created
string
The creation date of the platform
updated
string
The last updated date of the platform
name
string
The name of the platform
admins
array
List of admin users for the platform
description
string
A brief description of the platform
logo
string
URL to the platform's logo
url
string
URL of the platform
platformFee
number
The fee charged by the platform
activeSubscription
string
Active subscription identifier for the platform
Platforms Object
{
  "id": "plat_123e4567e89b12d3a456426614174000",
  "mode": "live",
  "created": "2023-05-21T10:00:00Z",
  "updated": "2023-06-21T10:00:00Z",
  "name": "Marketplace Platform",
  "admins": [],
  "description": "This is a marketplace platform.",
  "logo": "https://example.com/logo.png",
  "url": "https://marketplace.example.com",
  "platformFee": 2.5,
  "activeSubscription": "subs_123e4567e89b12d3a456426614174000"
}

Get platform by domain

Get the platform with the given domain

Parameters:

domain
string
The domain of the platform
GET
/platforms/domains/:domain
The Response
{
  "id": "plat_123e4567e89b12d3a456426614174000",
  "mode": "live",
  "created": "2023-05-21T10:00:00Z",
  "updated": "2023-06-21T10:00:00Z",
  "name": "Marketplace Platform",
  "admins": [],
  "description": "This is a marketplace platform.",
  "logo": "https://example.com/logo.png",
  "url": "https://marketplace.example.com",
  "platformFee": 2.5,
  "activeSubscription": "subs_123e4567e89b12d3a456426614174000"
}

Retrieve a platform

Get the platform with the given api key

Parameters:

No parameters
GET
/platforms
The Response
{
  "id": "plat_123e4567e89b12d3a456426614174000",
  "mode": "live",
  "created": "2023-05-21T10:00:00Z",
  "updated": "2023-06-21T10:00:00Z",
  "name": "Marketplace Platform",
  "admins": [],
  "description": "This is a marketplace platform.",
  "logo": "https://example.com/logo.png",
  "url": "https://marketplace.example.com",
  "platformFee": 2.5,
  "activeSubscription": "subs_123e4567e89b12d3a456426614174000"
}

Add an image to the platform

Upload an image using the media route and pass the id.

Parameters:

No parameters
POST
/platforms/:id/image
The Response
{
  "id": "plat_123e4567e89b12d3a456426614174000",
  "mode": "live",
  "created": "2023-05-21T10:00:00Z",
  "updated": "2023-06-21T10:00:00Z",
  "name": "Marketplace Platform",
  "admins": [],
  "description": "This is a marketplace platform.",
  "logo": "https://example.com/logo.png",
  "url": "https://marketplace.example.com",
  "platformFee": 2.5,
  "activeSubscription": "subs_123e4567e89b12d3a456426614174000"
}

Modify a platform by ID

Modify the platform with the given ID

Parameters:

No parameters
PUT
/platforms/:id
The Response
{
  "id": "plat_123e4567e89b12d3a456426614174000",
  "mode": "live",
  "created": "2023-05-21T10:00:00Z",
  "updated": "2023-06-21T10:00:00Z",
  "name": "Marketplace Platform",
  "admins": [],
  "description": "This is a marketplace platform.",
  "logo": "https://example.com/logo.png",
  "url": "https://marketplace.example.com",
  "platformFee": 2.5,
  "activeSubscription": "subs_123e4567e89b12d3a456426614174000"
}

Check user membership

Check if a user is in the community on the platform

Parameters:

No parameters
GET
/platforms/community/user/:user_id
The Response
{
  "id": "plat_123e4567e89b12d3a456426614174000",
  "mode": "live",
  "created": "2023-05-21T10:00:00Z",
  "updated": "2023-06-21T10:00:00Z",
  "name": "Marketplace Platform",
  "admins": [],
  "description": "This is a marketplace platform.",
  "logo": "https://example.com/logo.png",
  "url": "https://marketplace.example.com",
  "platformFee": 2.5,
  "activeSubscription": "subs_123e4567e89b12d3a456426614174000"
}

Waitlists

The waitlists resource in our API enables users to manage their platform's waitlist effectively. With endpoints to add individuals to the waitlist, list all members, and grant access to specific waitlist entries, this resource provides the essential tools for controlling access and engagement. These functionalities help maintain an organized and efficient waitlist management system, ensuring that user access is streamlined and easily managed.

Was this helful?
Yes
No

Endpoints

POST
/waitlists
GET
/waitlists/count
POST
/waitlists/:id/grant
DELETE
/waitlists/:id/remove

The Object

Attribute
Description
id
string
The unique identifier of the waitlist entry
email
string
The email address of the waitlist user
name
string
The name of the waitlist user
position
number
The position of the user on the waitlist
granted
string
The date when the user was granted access
Waitlists Object
{
  "id": "wlist_123e4567e89b12d3a456426614174000",
  "email": "waitlist@example.com",
  "name": "John Doe",
  "position": 1,
  "granted": "2023-06-21T10:00:00Z"
}

Add someone to the waitlist

Given an email, add someone to the waitlist

Parameters:

No parameters
POST
/waitlists
The Response
{
  "id": "wlist_123e4567e89b12d3a456426614174000",
  "email": "waitlist@example.com",
  "name": "John Doe",
  "position": 1,
  "granted": "2023-06-21T10:00:00Z"
}

Count everyone in the waitlist

This endpoint returns the number of people in the waitlist on the platform

Parameters:

No parameters
GET
/waitlists/count
The Response
{
  "id": "wlist_123e4567e89b12d3a456426614174000",
  "email": "waitlist@example.com",
  "name": "John Doe",
  "position": 1,
  "granted": "2023-06-21T10:00:00Z"
}

Grant access to the waitlist

This endpoint grants access to the waitlist with the given ID

Parameters:

No parameters
POST
/waitlists/:id/grant
The Response
{
  "id": "wlist_123e4567e89b12d3a456426614174000",
  "email": "waitlist@example.com",
  "name": "John Doe",
  "position": 1,
  "granted": "2023-06-21T10:00:00Z"
}

Remove from the waitlist

This endpoint removes someone from the waitlist with the given ID

Parameters:

No parameters
DELETE
/waitlists/:id/remove
The Response
{
  "id": "wlist_123e4567e89b12d3a456426614174000",
  "email": "waitlist@example.com",
  "name": "John Doe",
  "position": 1,
  "granted": "2023-06-21T10:00:00Z"
}

Users

The users resource in our API offers comprehensive management of user accounts, catering to both authenticated and unauthenticated interactions. Authenticated users can retrieve, modify, and delete their own accounts, manage their bank accounts and payment methods, and upload images or add links. Unauthenticated users have access to creating new accounts and managing user information through various endpoints. This robust set of features ensures seamless user account management, enhancing both administrative control and user experience on the platform.

Was this helful?
Yes
No

Endpoints

GET
/users/auth
PUT
/users/auth
DELETE
/users/auth
POST
/users/auth/image
POST
/users/auth/link
DELETE
/users/auth/link/:link_id
POST
/users/auth/bank_account
POST
/users/auth/client_secret
GET
/users/auth/payment_methods
DELETE
/users/auth/payment_methods/:payment_method_id
PUT
/users/auth/payment_methods/:payment_method_id/default
POST
/users
GET
/users/:id
GET
/users
PUT
/users/:id
DELETE
/users/:id
POST
/users/:id/image
POST
/users/:id/link
DELETE
/users/:id/link/:link_id
GET
/users/:id/bank_account
GET
/users/:id/payment_methods
DELETE
/users/:id/payment_methods/:payment_method_id
PUT
/users/:id/payment_methods/:payment_method_id/default

The Object

Attribute
Description
id
string
The unique identifier of the user
platform_id
string
The unique identifier of the platform associated with the user
email
string
The email address of the user
username
string
The username of the user
bio
string
Biography of the user
name
string
Full name of the user
firstName
string
First name of the user
lastName
string
Last name of the user
image
string
URL to the user's profile image
stripeConnectId
string
Stripe Connect ID associated with the user
chargesEnabled
boolean
Indicates if charges are enabled for the user
detailsSubmitted
boolean
Indicates if the user's details have been submitted
timezone
string
Timezone of the user
stripeCustomerId
string
Stripe Customer ID associated with the user
authenticated
string
Last authenticated date of the user
links
array
List of links associated with the user
paymentMethods
array
List of payment methods associated with the user
scheduledDeletion
string
Scheduled deletion date of the user
Users Object
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Retrieve User

Retrieve the user. Only available to authenticated users.

Parameters:

No parameters
GET
/users/auth
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Modify a user

Modify the user. Only available to authenticated users.

Parameters:

No parameters
PUT
/users/auth
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Schedule a user for deletion

Schedule the user. Only available to authenticated users.

Parameters:

No parameters
DELETE
/users/auth
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Add an image to the user

Upload an image for the user. Only available to authenticated users.

Parameters:

No parameters
POST
/users/auth/image
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Add a link to a user

Add a link for the user. Only available to authenticated users.

Parameters:

No parameters
POST
/users/auth/link
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Remove a link from a user

Remove a link for the user. Only available to authenticated users.

Parameters:

No parameters
DELETE
/users/auth/link/:link_id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Connect a user's bank account

Connect the user's bank account via Stripe Connect. Only available to authenticated users.

Parameters:

No parameters
POST
/users/auth/bank_account
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Set a user's client secret

Set the client secret of the user to be used for payments via Stripe or Candle Checkout. Only available to authenticated users.

Parameters:

No parameters
POST
/users/auth/client_secret
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

List a user's payment methods

List the payment methods linked to the user. Only available to authenticated users.

Parameters:

No parameters
GET
/users/auth/payment_methods
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Remove a user's payment method

Remove the payment method linked to the user. Only available to authenticated users.

Parameters:

No parameters
DELETE
/users/auth/payment_methods/:payment_method_id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Set a user's payment method as default

Set a payment method linked to the user's payment method as the default payment method. Only available to authenticated users.

Parameters:

No parameters
PUT
/users/auth/payment_methods/:payment_method_id/default
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Create a new user

Create a new user on the platform

Parameters:

No parameters
POST
/users
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Retrieve a user by ID

Retrieve the user with the given ID

Parameters:

No parameters
GET
/users/:id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

List users

List all users on the platform

Parameters:

No parameters
GET
/users
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Modify a user by ID

Modify the user with the given ID

Parameters:

No parameters
PUT
/users/:id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Schedule a user for deletion

Schedule the user with the given ID for deletion

Parameters:

No parameters
DELETE
/users/:id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Add an image for the user

Upload an image for the user with the given ID

Parameters:

No parameters
POST
/users/:id/image
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Add a link for the user

Add a link for the user with the given ID

Parameters:

No parameters
POST
/users/:id/link
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Remove a link for the user

Remove a link for the user with the given ID

Parameters:

No parameters
DELETE
/users/:id/link/:link_id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Retrieve a user's bank account

Retrieve the bank account linked via Stripe Connect for the user with the given ID

Parameters:

No parameters
GET
/users/:id/bank_account
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

List a user's payment methods

List the payment methods linked to the user with the given ID

Parameters:

No parameters
GET
/users/:id/payment_methods
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Remove a user's payment method

Remove the payment method linked to the user with the given ID

Parameters:

No parameters
DELETE
/users/:id/payment_methods/:payment_method_id
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Set a user's payment method as default

Set a payment method linked to the user with the given ID as the default payment method

Parameters:

No parameters
PUT
/users/:id/payment_methods/:payment_method_id/default
The Response
{
  "id": "user_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "email": "user@example.com",
  "username": "john_doe",
  "bio": "I am a software engineer.",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "image": "https://example.com/profile.jpg",
  "stripeConnectId": "acct_123e4567e89b12d3a456426614174000",
  "chargesEnabled": true,
  "detailsSubmitted": true,
  "timezone": "America/New_York",
  "stripeCustomerId": "cus_123e4567e89b12d3a456426614174000",
  "authenticated": "2023-06-21T10:00:00Z",
  "links": [],
  "paymentMethods": [],
  "scheduledDeletion": "2023-12-31T23:59:59Z"
}

Products

The products resource in our API is designed to provide comprehensive product management capabilities for your platform. With endpoints to create, list, retrieve, modify, and delete products, you can effectively manage your product inventory. Additional functionalities include managing prices, setting seasonal pricing, and enabling or disabling products. These features offer a robust solution for maintaining and updating product information, ensuring your platform can adapt to changing needs and offer the best experience for your users.

Was this helful?
Yes
No

Endpoints

POST
/products
GET
/products
GET
/products/user/:user_id
GET
/products/categories
GET
/products/:id
PUT
/products/:id
DELETE
/products/:id
GET
/products/:id/prices
POST
/products/:id/prices
DELETE
/products/:id/prices/:price_id
PUT
/products/:id/prices/usage
PUT
/products/:id/enable
PUT
/products/:id/disable

The Object

Attribute
Description
id
string
The unique identifier of the product
platform_id
string
The unique identifier of the platform associated with the product
user_id
string
The unique identifier of the user who created the product
parent_product_id
string
The unique identifier of the parent product, if any
name
string
The name of the product
description
string
A brief description of the product
image
string
URL to the product's image
quantity
number
The available quantity of the product
isAvailableInStock
boolean
Indicates if the product is available in stock
isEnabled
boolean
Indicates if the product is enabled for sale
category
string
The category of the product
subcategory
string
The subcategory of the product
tags
array
List of tags associated with the product
price
number
The price of the product
seasonalPrices
array
List of seasonal prices for the product
Products Object
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Create a product

Create a product on the platform

Parameters:

No parameters
POST
/products
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

List all products

List all products on the platform

Parameters:

No parameters
GET
/products
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

List a user's product

List all products on the platform for the given user

Parameters:

No parameters
GET
/products/user/:user_id
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

List product categories

List all categories across all products on the platform

Parameters:

No parameters
GET
/products/categories
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Retrieve a product by id

Retrieve the product with the given ID

Parameters:

No parameters
GET
/products/:id
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Modify a product by id

Modify the product with the given ID

Parameters:

No parameters
PUT
/products/:id
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Delete a product

Delete the product with the given ID

Parameters:

No parameters
DELETE
/products/:id
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

List prices for a product

List all prices for the product with the given ID

Parameters:

No parameters
GET
/products/:id/prices
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Add a seasonal price on product

Add a seasonal price on the product with the given ID

Parameters:

No parameters
POST
/products/:id/prices
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Remove a seasonal price from a product

Remove a seasonal price from the product with the given ID

Parameters:

No parameters
DELETE
/products/:id/prices/:price_id
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Set seasonal price usage

Set whether or not to use seasonal prices for the product with the given ID

Parameters:

No parameters
PUT
/products/:id/prices/usage
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Enable a product

Enable the product with the given ID

Parameters:

No parameters
PUT
/products/:id/enable
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Disable a product

Disable the product with the given ID

Parameters:

No parameters
PUT
/products/:id/disable
The Response
{
  "id": "prod_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "parent_product_id": "prod_123e4567e89b12d3a456426614174000",
  "name": "Sample Product",
  "description": "This is a sample product description.",
  "image": "https://example.com/product.jpg",
  "quantity": 100,
  "isAvailableInStock": true,
  "isEnabled": true,
  "category": "Electronics",
  "subcategory": "Mobile Phones",
  "tags": [
    "tag1",
    "tag2"
  ],
  "price": 299.99,
  "seasonalPrices": []
}

Contracts

Our platform offers a comprehensive suite of contract management features designed to streamline the creation, modification, and tracking of agreements. From initiating new contracts and managing items, buyers, and sellers, to handling fees and settlements, the platform provides robust tools for both administrators and users. Whether you are creating contracts from scratch or integrating them with existing carts, our system ensures efficient and flexible management of all contractual aspects, catering to diverse needs and scenarios.

Was this helful?
Yes
No

Endpoints

POST
/contracts
POST
/contracts/cart/:cart_id
GET
/contracts
GET
/contracts/user/:user_id/buyer
GET
/contracts/user/:user_id/seller
GET
/contracts/auth
GET
/contracts/:id
DELETE
/contracts/:id
PUT
/contracts/:id
POST
/contracts/:id/item
DELETE
/contracts/:id/item/:item_id
POST
/contracts/:id/buyer
PUT
/contracts/:id/buyer/:buyer_id/due
DELETE
/contracts/:id/buyer/:buyer_id
POST
/contracts/:id/seller
PUT
/contracts/:id/seller/:seller_id/owed
DELETE
/contracts/:id/seller/:seller_id
POST
/contracts/:id/fee
DELETE
/contracts/:id/fee/:fee_id
PUT
/contracts/:id/fee/:fee_id
PUT
/contracts/:id/fee_inclusion
POST
/contracts/:id/send
PUT
/contracts/:id/settle
GET
/contracts/:id/sync

The Object

Attribute
Description
id
string
The unique identifier of the contract
platform_id
string
The unique identifier of the platform associated with the contract
user_id
string
The unique identifier of the user associated with the contract
items
array
List of items included in the contract
notes
string
Notes related to the contract
sent
string
The date when the contract was sent
lastSent
string
The last date when the contract was sent
due
string
The due date for the contract
lastPaymentAttempt
string
The last payment attempt date for the contract
paid
string
The date when the contract was paid
subTotal
number
The subtotal amount of the contract
total
number
The total amount of the contract
currency
string
The currency used in the contract
status
string
The status of the contract
buyers
array
List of buyers associated with the contract
sellers
array
List of sellers associated with the contract
fees
array
List of fees associated with the contract
includeStripeFees
boolean
Indicates if Stripe fees are included in the contract
includeCandleFees
boolean
Indicates if Candle fees are included in the contract
includePlatformFees
boolean
Indicates if platform fees are included in the contract
Contracts Object
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Create a new contract

Create a new contract on the platform

Parameters:

No parameters
POST
/contracts
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Create a new contract from a cart

Create a new contract on the platform

Parameters:

No parameters
POST
/contracts/cart/:cart_id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

List contracts

List all contracts on the platform

Parameters:

No parameters
GET
/contracts
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

List contracts where the user is the buyer

List all contracts on the platform where the user is the buyer

Parameters:

No parameters
GET
/contracts/user/:user_id/buyer
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

List contracts where the user is the seller

List all contracts on the platform where the user is the seller

Parameters:

No parameters
GET
/contracts/user/:user_id/seller
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

List contracts authenticated user is on

List all contracts on the platform where the authenticated user is on

Parameters:

No parameters
GET
/contracts/auth
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Retrieve a contract by ID

Retrieve the contract with the given ID

Parameters:

No parameters
GET
/contracts/:id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Delete a contract by ID

Delete the contract with the given ID

Parameters:

No parameters
DELETE
/contracts/:id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Modify a contract by ID

Modify the contract with the given ID

Parameters:

No parameters
PUT
/contracts/:id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Add an item to a contract

Add an item to the contract with the given ID

Parameters:

No parameters
POST
/contracts/:id/item
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Remove an item from a contract

Remove an item from the contract with the given ID

Parameters:

No parameters
DELETE
/contracts/:id/item/:item_id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Add a buyer to a contract

Add a buyer to the contract with the given ID

Parameters:

No parameters
POST
/contracts/:id/buyer
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Modify a buyer's due amount

Modify the buyer's due amount for the contract with the given ID

Parameters:

No parameters
PUT
/contracts/:id/buyer/:buyer_id/due
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Remove a buyer from a contract

Remove a buyer from the contract with the given ID

Parameters:

No parameters
DELETE
/contracts/:id/buyer/:buyer_id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Add a seller to a contract

Add a seller to the contract with the given ID

Parameters:

No parameters
POST
/contracts/:id/seller
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Modify a seller's owed amount

Modify the seller's owed amount for the contract with the given ID

Parameters:

No parameters
PUT
/contracts/:id/seller/:seller_id/owed
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Remove a seller from a contract

Remove a seller from the contract with the given ID

Parameters:

No parameters
DELETE
/contracts/:id/seller/:seller_id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Add a custom fee to a contract

Add a fee to the contract with the given ID

Parameters:

No parameters
POST
/contracts/:id/fee
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Remove a custom fee from a contract

Remove a fee from the contract with the given ID

Parameters:

No parameters
DELETE
/contracts/:id/fee/:fee_id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Modify custom fees on a contract

Update the fees on the contract with the given ID

Parameters:

No parameters
PUT
/contracts/:id/fee/:fee_id
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Set fee inclusion on a contract

This endpoint sets whether or not fees are included in the contract price. Setting the fee inclusion to true will mean the buyer pays the all fees on the platform.

Parameters:

No parameters
PUT
/contracts/:id/fee_inclusion
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Send a contract by ID

Send the contract with the given ID

Parameters:

No parameters
POST
/contracts/:id/send
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Settle a contract

Settle the contract with the given ID

Parameters:

No parameters
PUT
/contracts/:id/settle
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Rebalance a contract

This endpoint makes sure that the values set on the contract are add up, that what the buyers due is equal to what the sellers are owed minus fees.

Parameters:

No parameters
GET
/contracts/:id/sync
The Response
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": [],
  "notes": "This is a sample contract note.",
  "sent": "2023-06-21T10:00:00Z",
  "lastSent": "2023-06-21T10:00:00Z",
  "due": "2023-07-21T10:00:00Z",
  "lastPaymentAttempt": "2023-06-30T10:00:00Z",
  "paid": "2023-07-01T10:00:00Z",
  "subTotal": 90,
  "total": 100,
  "currency": "usd",
  "status": "open",
  "buyers": [],
  "sellers": [],
  "fees": [],
  "includeStripeFees": true,
  "includeCandleFees": true,
  "includePlatformFees": true
}

Carts

Subscription management is complemented by a robust cart system that enables users to efficiently manage their shopping experience. Authenticated users can add, modify, or remove products from their cart, and view the contents at any time. Additionally, users have the option to clear their cart entirely, ensuring a smooth and flexible shopping process tailored to individual needs.

Was this helful?
Yes
No

Endpoints

POST
/carts/auth/product/:product_id
GET
/carts/auth
DELETE
/carts/auth/item/:cart_item_id
DELETE
/carts/auth

The Object

Attribute
Description
id
string
The unique identifier of the cart
platform_id
string
The unique identifier of the platform associated with the cart
user_id
string
The unique identifier of the user who owns the cart
items
array
List of items in the cart
Carts Object
{
  "id": "cart_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": []
}

Add a product to a user's cart

Add a product to an authenticated user's cart

Parameters:

No parameters
POST
/carts/auth/product/:product_id
The Response
{
  "id": "cart_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": []
}

Retrieve a user's cart

List all items in a user's cart

Parameters:

No parameters
GET
/carts/auth
The Response
{
  "id": "cart_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": []
}

Remove an item from a user's cart

Remove a product from an authenticated user's cart

Parameters:

No parameters
DELETE
/carts/auth/item/:cart_item_id
The Response
{
  "id": "cart_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": []
}

Clear a user's cart

Clear an authenticated user's cart

Parameters:

No parameters
DELETE
/carts/auth
The Response
{
  "id": "cart_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "items": []
}

Subscriptions

Our platform supports comprehensive subscription management to enhance user engagement and streamline recurring transactions. Authenticated users can easily subscribe to contracts, while detailed functionalities allow users to list, retrieve, pause, resume, or end their subscriptions as needed. This ensures flexible and efficient handling of subscription-based interactions, providing seamless control over recurring engagements and account management.

Was this helful?
Yes
No

Endpoints

POST
/subscriptions/auth/contract/:contract_id
GET
/subscriptions/user/:user_id
GET
/subscriptions/:id
PUT
/subscriptions/:id/pause
PUT
/subscriptions/auth/:id/resume
DELETE
/subscriptions/auth/:id

The Object

Attribute
Description
id
string
The unique identifier of the subscription
platform_id
string
The unique identifier of the platform associated with the subscription
user_id
string
The unique identifier of the user who owns the subscription
service_id
string
The unique identifier of the service associated with the subscription
price
number
The price of the subscription
isActive
boolean
Indicates if the subscription is active
isPaused
boolean
Indicates if the subscription is paused
pausedAt
string
The date when the subscription was paused
pausedUntil
string
The date until which the subscription is paused
cycle
string
The billing cycle of the subscription
startDate
string
The start date of the subscription
ended
string
The end date of the subscription
Subscriptions Object
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

Subscription to a contract

Create a new subscription on the platform as an authenticated user off of a contract

Parameters:

No parameters
POST
/subscriptions/auth/contract/:contract_id
The Response
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

List a user's subscriptions

List all subscriptions on the platform for a given user id

Parameters:

No parameters
GET
/subscriptions/user/:user_id
The Response
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

Retrieve a subscription

Retrieve a subscription on the platform by id

Parameters:

No parameters
GET
/subscriptions/:id
The Response
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

Pause a subscription

Pause a subscription on the platform by id

Parameters:

No parameters
PUT
/subscriptions/:id/pause
The Response
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

Resume a subscription

Resume a subscription on the platform by id. Requires authentication.

Parameters:

No parameters
PUT
/subscriptions/auth/:id/resume
The Response
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

End a subscription

End a subscription on the platform by id

Parameters:

No parameters
DELETE
/subscriptions/auth/:id
The Response
{
  "id": "subs_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "service_id": "serv_123e4567e89b12d3a456426614174000",
  "price": 99.99,
  "isActive": true,
  "isPaused": false,
  "pausedAt": "2023-06-21T10:00:00Z",
  "pausedUntil": "2023-07-21T10:00:00Z",
  "cycle": "monthly",
  "startDate": "2023-01-01T00:00:00Z",
  "ended": "2023-12-31T23:59:59Z"
}

Calendars

Managing calendar events and availability is streamlined with features designed for both users and administrators. Authenticated users can effortlessly add, modify, or remove events from their personal calendars, while also accessing their calendar of events. For administrators and users, retrieving availability and making modifications are straightforward processes, ensuring that schedules are up-to-date and accurately reflect current commitments.

Was this helful?
Yes
No

Endpoints

POST
/calendars/auth/availability
GET
/calendars/auth
GET
/calendars/user/:user_id/availability
POST
/calendars/auth/event
GET
/calendars/auth/event/:event_id
PUT
/calendars/auth/event/:event_id
DELETE
/calendars/auth/event/:event_id
PUT
/calendars/auth/availability

The Object

Attribute
Description
id
string
The unique identifier of the calendar
platform_id
string
The unique identifier of the platform associated with the calendar
user_id
string
The unique identifier of the user who owns the calendar
name
string
The name of the calendar
description
string
A brief description of the calendar
googleCalendarIds
array
List of Google Calendar IDs integrated with this calendar
availability
array
List of availability schedules for the calendar
events
array
List of events scheduled in the calendar
Calendars Object
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Set user's availability

Set a user's full availability on the platform for a given authenticated user

Parameters:

No parameters
POST
/calendars/auth/availability
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Retrieve a user's calendar events

Retrieve an authenticated user's calendar of events

Parameters:

No parameters
GET
/calendars/auth
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Retrieve a user's availability

Retrieve a user's full availability on the platform for a given user id

Parameters:

No parameters
GET
/calendars/user/:user_id/availability
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Add an event to a user's calendar

Add an event to an authenticated user's calendar

Parameters:

No parameters
POST
/calendars/auth/event
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Retrieve an event on a user's calendar

Retrieve an event on an authenticated user's calendar

Parameters:

No parameters
GET
/calendars/auth/event/:event_id
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Modify an event on a user's calendar

Modify an event on an authenticated user's calendar

Parameters:

No parameters
PUT
/calendars/auth/event/:event_id
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Remove an event from a user's calendar

Remove a non-subscription event from an authenticated user's calendar. Only available to authenticated users and only for events that are not subscriptions.

Parameters:

No parameters
DELETE
/calendars/auth/event/:event_id
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Modify a user's availability

Modify a user's full availability on the platform for a given user id

Parameters:

No parameters
PUT
/calendars/auth/availability
The Response
{
  "id": "cal_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "user_id": "user_123e4567e89b12d3a456426614174000",
  "name": "Work Schedule",
  "description": "This calendar contains the user's work schedule.",
  "googleCalendarIds": [
    "google_cal_1",
    "google_cal_2"
  ],
  "availability": [],
  "events": []
}

Transactions

Our platform provides a range of transaction management features that offer valuable insights and oversight into financial activities. From listing all transactions and tracking individual revenues and expenditures, to identifying top spenders and earners, our system equips you with essential data to monitor and analyze financial performance. Key metrics such as platform volume, cart value, and recurring revenue (MRR and ARR) are readily accessible, enabling comprehensive financial management and strategic decision-making.

Was this helful?
Yes
No

Endpoints

GET
/transactions/user/:user_id/revenue
GET
/transactions/user/:user_id/spend

The Object

Attribute
Description
id
string
The unique identifier of the transaction
platform_id
string
The unique identifier of the platform associated with the transaction
contract_id
string
The unique identifier of the contract associated with the transaction
buyer_user_id
string
The unique identifier of the buyer user involved in the transaction
seller_user_id
string
The unique identifier of the seller user involved in the transaction
amount
number
The transaction amount
currency
string
The currency used in the transaction
stripeChargeId
string
The Stripe charge ID associated with the transaction
type
string
The type of transaction
status
string
The status of the transaction
Transactions Object
{
  "id": "tran_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "contract_id": "inv_123e4567e89b12d3a456426614174000",
  "buyer_user_id": "user_123e4567e89b12d3a456426614174000",
  "seller_user_id": "user_123e4567e89b12d3a456426614174000",
  "amount": 150,
  "currency": "usd",
  "stripeChargeId": "ch_123e4567e89b12d3a456426614174000",
  "type": "outgoing",
  "status": "succeeded"
}

Retrieve a buyer's revenue

Returns the revenue of the buyer with the given ID

Parameters:

No parameters
GET
/transactions/user/:user_id/revenue
The Response
{
  "id": "tran_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "contract_id": "inv_123e4567e89b12d3a456426614174000",
  "buyer_user_id": "user_123e4567e89b12d3a456426614174000",
  "seller_user_id": "user_123e4567e89b12d3a456426614174000",
  "amount": 150,
  "currency": "usd",
  "stripeChargeId": "ch_123e4567e89b12d3a456426614174000",
  "type": "outgoing",
  "status": "succeeded"
}

Retrieve a seller's spend

Returns the spend of the seller with the given ID

Parameters:

No parameters
GET
/transactions/user/:user_id/spend
The Response
{
  "id": "tran_123e4567e89b12d3a456426614174000",
  "platform_id": "plat_123e4567e89b12d3a456426614174000",
  "contract_id": "inv_123e4567e89b12d3a456426614174000",
  "buyer_user_id": "user_123e4567e89b12d3a456426614174000",
  "seller_user_id": "user_123e4567e89b12d3a456426614174000",
  "amount": 150,
  "currency": "usd",
  "stripeChargeId": "ch_123e4567e89b12d3a456426614174000",
  "type": "outgoing",
  "status": "succeeded"
}

Utils

For utilities, there are two endpoints that can be utilized without requiring authentication or an API key. The first endpoint generates a username based on provided text, while the second estimates fees for a given amount in cents. Both endpoints are designed to be straightforward, making them accessible and easy to use.

Was this helful?
Yes
No

Endpoints

POST
/utils/gnerate/username
POST
/utils/estimate/fee
POST
/utils/media/upload

Generate a username

Generate a username based on the given text

Parameters:

No parameters
POST
/utils/gnerate/username
The Response
{}

Estimate fees

Estimate fees for the given amount. The amount is in cents.

Parameters:

No parameters
POST
/utils/estimate/fee
The Response
{}

Upload media

Upload a media file. File types supported: jpeg, jpg, png, gif.

Parameters:

No parameters
POST
/utils/media/upload
The Response
{}