API Documentation

The Coinsub API is designed to help merchants manage subscriptions and purchases seamlessly.

Overview

This API allows merchants to manage subscriptions and purchases. All endpoints require authentication using Merchant-ID and API-Key headers.

Authentication

All API requests must include the following headers for authentication:

• Merchant-ID: The unique identifier assigned to each merchant.

• API-Key: The API key generated through the merchant dashboard.

Generating API Keys

To generate and manage your API keys:

1. Log into app.coinsub.io with your wallet.

2. Navigate to Settings.

3. Click on Click here to manage API Keys.

Note: API keys can be disabled but not re-enabled. To disable an API key, go to the Your API Keys page, locate the key you wish to disable, and click Disable.

API Endpoints

1. Check the Subscription Status of a Product with a Subscriber ID

Endpoint: POST https://api.coinsub.io/v1/check_subscription_status_product

Description: This endpoint checks whether a subscriber has an active subscription for a specific product. If the subscription is active, it returns active: true; otherwise, it returns active: false.

Request Headers:

• Merchant-ID: Unique identifier for the merchant.

• API-Key: API key.

Request Body:

{
  "subscriber_id": "uuid",
  "subscription_product_id": "integer"
}

Success Response Example (Subscription is active):

{
  "active": true,
  "subscriber_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscription_product_id": 1
}

Failure Response Example (Subscription is inactive or doesn't exist):

{
  "active": false,
  "subscriber_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscription_product_id": 1
}

Error Responses:

• 400 Bad Request: The request payload is invalid or the Merchant-ID format is incorrect.

• 401 Unauthorized: The provided API-Key is invalid or missing.

• 404 Not Found: The specified subscriber_id or subscription_product_id does not exist.

• 500 Internal Server Error: An error occurred on the server while retrieving the subscription status.

2. Check the Subscription Status of a Product with a Subscriber’s Metadata

Endpoint: POST https://api.coinsub.io/v1/check_subscription_by_metadata

Description: This endpoint checks the subscription status of a subscriber based on metadata. It returns one of three responses: active subscription, inactive subscription, or no matching subscription.

Request Headers:

• Merchant-ID: Unique identifier for the merchant.

• API-Key: API key.

Request Body:

{
  "subscription_product_id": "uuid",
  "metadata": {
    "key": "value"
  }
}

Response Examples:

• Active Subscription:

  {
    "active": true,
    "subscriber_id": "123e4567-e89b-12d3-a456-426614174000",
    "metadata": {
      "customerId": "1212424128"
    },
    "subscription_product_id": 1
  }

• Inactive Subscription:

  {
    "active": false,
    "subscriber_id": "123e4567-e89b-12d3-a456-426614174000",
    "metadata": {
      "customerId": "1212424128"
    },
    "subscription_product_id": 2
  }

• No Matching Subscription:

  {
    "active": false,
    "metadata": {
      "customerId": "1212424128"
    },
    "subscription_product_id": 3
  }

3. Get a List of a Merchant’s Products

Endpoint: GET https://api.coinsub.io/v1/products

Description: Retrieves a list of products available from the merchant. Each product will be categorized as either a "subscription" or "One-Off" type.

Request Headers:

• Merchant-ID: Unique identifier for the merchant.

• API-Key: API key.

Response Example:

[
  {
    "subscription_product_id": 1,
    "subscription_name": "Basic Plan",
    "product_type": "subscription"
  },
  {
    "subscription_product_id": 2,
    "subscription_name": "Pro Plan",
    "product_type": "subscription"
  },
  {
    "subscription_product_id": 3,
    "subscription_name": "A Beginner’s Guide (Hardcover)",
    "product_type": "One-Off"
  }
]

4. Check Active Subscriptions and Purchases by a Customer’s Subscriber ID

Endpoint: GET https://api.coinsub.io/v1/active_subscriptions_and_purchases/{subscriber_id}

Endpoint Example: GET https://api.coinsub.io/v1/active_subscriptions_and_purchases/123e4567-e89b-12d3-a456-426614174000

Description: Retrieves active subscriptions and one-off purchases for a given subscriber ID.

Request Headers:

• Merchant-ID: Unique identifier for the merchant.

• API-Key: API key.

Response Example:

{
  "subscriber_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscriptions": [
    {
      "subscription_id": 1,
      "subscription_product_id": 1,
      "subscription_name": "Basic Plan",
      "start_date": "2023-01-01T00:00:00Z",
      "duration_days": 30,
      "last_payment_processed": "2023-01-15T00:00:00Z",
      "next_payment_due": "2023-02-01T00:00:00Z",
      "amount": 1000,
      "status": "active",
      "created_on": "2023-01-01T00:00:00Z",
      "metadata": {
        "name": "Jane Doe"
      }
    }
  ],
  "purchases": [
    {
      "subscription_id": 2,
      "subscription_product_id": 2,
      "subscription_name": "A Beginner’s Guide (Hardcover)",
      "start_date": "2023-01-01T00:00:00Z",
      "duration_days": 365,
      "last_payment_processed": "2023-01-01T00:00:00Z",
      "amount": 12000,
      "status": "completed",
      "created_on": "2023-01-01T00:00:00Z",
      "metadata": {
        "name": "Jane Doe"
      }
    }
  ]
}

Error Responses:

• 400 Bad Request: The subscriber_id or Merchant-ID format is invalid.

• 401 Unauthorized: The provided API-Key is invalid or missing.

• 404 Not Found: The specified subscriber_id does not exist.

• 500 Internal Server Error: An error occurred on the server while retrieving active subscriptions and purchases.

5. Check Active Subscriptions and Purchases by a Customer’s Metadata

Endpoint: POST https://api.coinsub.io/v1/active_subscriptions_and_purchases_by_only_metadata

Description: This endpoint retrieves active subscriptions and purchases based on the provided customer metadata.

Request Headers:

• Merchant-ID: Unique identifier for the merchant.

• API-Key: API key.

Request Example:

{
  "metadata": {
    "key": "value"
  }
}

Response Example:

{
  "metadata": {
    "key": "value"
  },
  "subscriptions": [
    {
      "subscription_id": 1,
      "subscription_product_id": 1,
      "subscription_name": "Basic Plan",
      "start_date": "2023-01-01T00:00:00Z",
      "duration_days": 30,
      "last_payment_processed": "2023-01-15T00:00:00Z",
      "next_payment_due": "2023-02-01T00:00:00Z",
      "amount": 1000,
      "status": "active",
      "created_on": "2023-01-01T00:00:00Z",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "purchases": [
    {
      "subscription_id": 2,
      "subscription_product_id": 2,
      "subscription_name": "Pro Plan",
      "start_date": "2023-01-01T00:00:00Z",
      "duration_days": 365,
      "last_payment_processed": "2023-01-01T00:00:00Z",
      "amount": 12000,
      "status": "completed",
      "created_on": "2023-01-01T00:00:00Z",
      "metadata": {
        "key": "value"
      }
    }
  ]
}

No Metadata Match Response Example:

{
  "metadata": {
    "key": "value"
  },
  "