API Reference

These APIs cover the management of checkout, products, customers, transactions, licenses, discount codes, and subscriptions, suitable for handling e-commerce operations and account management.

General Information

1. Base URL

The Paylinker API is built on REST principles. All requests must use HTTPS to ensure data security, integrity, and privacy. The API does not support HTTP requests.

Base URL:

https://api.paylinker.com

All API request paths are based on this URL, and subsequent request paths will be appended to this base URL.

2. Authentication

The API uses API Keys for authentication. You need to pass your API key in the x-api-key header of each request.

Example:

{
  "headers": {
    "x-api-key": "paylinker_123456789"
  }
}

You must include a valid API key in every request to successfully access Paylinker API services.

3. Response Codes

These response codes follow standard HTTP status codes to help developers understand the status of their requests.

Code	Description
200	Request successful.
400	Invalid request parameters. Often due to missing required parameters or incorrect format.
401	Missing API key or incorrect key.
403	Invalid API key provided.
404	Resource not found.
429	Rate limit exceeded.
500	Paylinker server error.

4. Request Example

In practice, all API requests will use https://api.paylinker.com as the base path. Specific API paths are appended to it to form the full request URL. For example, the API request address to create a checkout session is:

https://api.paylinker.com/create-checkout

These details help developers understand how to interact securely with the Paylinker API, clearly master how to use API keys for authentication, and how to handle common HTTP error codes.

5. Other Notes

• All request Content-Type must be application/json.
• If the request involves large amounts of data, consider using pagination mechanisms.
• A 429 error means you have exceeded the request limit. Try waiting for a while before making the request again.

Endpoints

1. Checkout

Create Checkout Session

Create a new checkout session for a customer.

• Endpoint: POST /create-checkout
• Parameters:
  • product_id (string): Unique ID of the product.
  • quantity (integer): Quantity to purchase.
  • customer_id (string): Unique ID of the customer.
  • coupon_code (string, optional): Discount code if applicable.

Request Example:

{
  "product_id": "abc123",
  "quantity": 2,
  "customer_id": "cus_456789",
  "coupon_code": "SUMMER20"
}

Response:

• 200: Returns the checkout session URL.
• 400: Invalid parameters (e.g., missing product_id or quantity).

Get Checkout Session

Retrieve details of an existing checkout session.

• Endpoint: GET /get-checkout
• Parameters:
  • checkout_session_id (string): The ID of the checkout session to retrieve.

Request Example:

{
  "checkout_session_id": "sess_123456"
}

Response:

• 200: Returns detailed information about the checkout session.
• 404: Checkout session not found.

2. Product

Create Product

Create a new product in the catalog.

• Endpoint: POST /create-product
• Parameters:
  • name (string): Product name.
  • description (string): Product description.
  • price (number): Product price.
  • currency (string): Currency code (e.g., "USD").
  • image_url (string, optional): URL of the product image.

Request Example:

{
  "name": "Awesome Widget",
  "description": "An awesome widget to make your life easier.",
  "price": 19.99,
  "currency": "USD",
  "image_url": "https://example.com/widget.jpg"
}

Response:

• 200: Returns the created product details.
• 400: Invalid parameters (e.g., name or price requirements not met).

Get Product

Retrieve details of a specific product.

• Endpoint: GET /get-product
• Parameters:
  • product_id (string): The ID of the product to retrieve.

Request Example:

{
  "product_id": "abc123"
}

Response:

• 200: Returns detailed information about the product.
• 404: Product not found.

Search Products

List all products.

• Endpoint: GET /search-products
• Description: Retrieve a list of all available products.

3. Customer

Get Customer

Retrieve details of a specific customer.

• Endpoint: GET /get-customer
• Parameters:
  • customer_id (string): Unique ID of the customer.

Request Example:

{
  "customer_id": "cus_456789"
}

Response:

• 200: Returns detailed information about the customer.
• 404: Customer not found.

List Customers

Get a list of customers.

• Endpoint: GET /list-customers

Create Customer Billing

Create billing information for a customer.

• Endpoint: POST /create-customer-billing

4. Discount Code

Create Discount Code

Create a new discount code.

• Endpoint: POST /create-discount-code
• Parameters:
  • code (string): The discount code string.
  • discount_percentage (number): The percentage discount.
  • valid_from (string, optional): Start date (ISO format).
  • valid_until (string, optional): End date (ISO format).

Request Example:

{
  "code": "SUMMER20",
  "discount_percentage": 20,
  "valid_from": "2025-06-01",
  "valid_until": "2025-06-30"
}

Response:

• 200: Returns the created discount code details.
• 400: Invalid format or parameters.

Delete Discount Code

Delete a discount code.

• Endpoint: DEL /delete-discount-code

Get Discount Code

Retrieve a discount code.

• Endpoint: GET /get-discount-code

5. Transactions

Get Transactions

List all transactions.

• Endpoint: GET /get-transactions

6. License

Validate License

Validate a license key.

• Endpoint: POST /validate-license

Activate License

Activate a license key.

• Endpoint: POST /activate-license

Deactivate License

Deactivate a license key.

• Endpoint: POST /deactivate-license

7. Subscription

Get Subscription

Retrieve subscription information.

• Endpoint: GET /get-subscription
• Parameters:
  • subscription_id (string): The unique ID of the subscription.

Request Example:

{
  "subscription_id": "sub_123456"
}

Response:

• 200: Returns detailed information about the subscription.
• 404: Subscription not found.

Update Subscription

Update a subscription's details, such as quantity or plan.

• Endpoint: POST /update-subscription
• Parameters:
  • subscription_id (string): The unique ID of the subscription.
  • plan_id (string, optional): New plan ID to switch to.
  • quantity (integer, optional): New quantity for the subscription.

Request Example:

{
  "subscription_id": "sub_123456",
  "quantity": 5
}

Response:

• 200: Returns the updated subscription details.
• 400: Invalid parameters.

Upgrade Subscription

Upgrade a subscription to a higher tier.

• Endpoint: POST /upgrade-subscription
• Parameters:
  • subscription_id (string): The unique ID of the subscription.
  • new_plan_id (string): The ID of the new plan to upgrade to.

Request Example:

{
  "subscription_id": "sub_123456",
  "new_plan_id": "plan_pro_yearly"
}

Response:

• 200: Returns the upgraded subscription details.
• 400: Invalid plan or subscription status.

Cancel Subscription

Cancel a subscription.

• Endpoint: POST /cancel-subscription
• Parameters:
  • subscription_id (string): The unique ID of the subscription.
  • cancel_at_period_end (boolean, optional): If true, the subscription will cancel at the end of the current billing period. Defaults to false (immediate cancellation).

Request Example:

{
  "subscription_id": "sub_123456",
  "cancel_at_period_end": true
}

Response:

• 200: Returns the cancelled subscription details.
• 404: Subscription not found.