Skip to main content

Getting Started

This guide will help you make your first API call to OK Capsule.

Full API Reference

Response examples are simplified. See the Interactive API Documentation for complete response schemas.

Before You Begin: Account and Brand Setup​

New to OK Capsule API?

Before contacting OK Capsule about API credentials, your account and brand must be set up first.

Required setup sequence:

  1. Set up your account — Your OK Capsule account must be created and active.
  2. Set up your brand — At least one brand (Product Line) must be configured in your account.
  3. Contact OK Capsule about API credentials — Once account and brand setup are complete, reach out to your OK Capsule representative to discuss API access.

If you have not completed steps 1 and 2, start there before proceeding. Contact your OK Capsule representative if you need help with account or brand setup.

Quick Start Checklist​

Before you can create orders, ensure you have:

  • Account set up - Your OK Capsule account is active
  • Brand configured - At least one Product Line is set up in your account
  • API credentials - Obtained from your OK Capsule representative after account and brand setup
  • Active products - At least one product configured in your catalog
  • Packaging configured - Packaging Asset Group (PAG) set up by OK Capsule
New Client?

Your products and packaging will be configured during onboarding. Contact your account representative if you're unsure about your setup status.

Shopify Integration

Many clients integrate via the OK Capsule Shopify App, which handles order submission automatically. If you're using Shopify, you may not need to call the API directly. These docs are for clients who need direct API access or want a deeper understanding of the API.

Prerequisites​

  • API credentials (contact your OK Capsule account representative)
  • An HTTP client of your choice

Step 1: Authentication​

OK Capsule uses OAuth 2.0 for authentication. First, obtain an access token:

const response = await fetch("https://na1-prod.okcapsule.app/v2/authentication/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "your-email@example.com",
    password: "your-password",
  }),
});

const { access_token, refresh_token } = await response.json();

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "expires_in": 86400
}
Token Expiration

Access tokens expire after 24 hours. Use the refresh token to obtain a new access token without re-authenticating. Store both tokens securely - you'll need the refresh token to avoid re-authenticating.

Token Security Best Practices​

Security recommendations for handling tokens

Storage:

  • ✅ Store tokens in secure, encrypted storage (e.g., environment variables, secrets manager)
  • ✅ Use server-side storage - never expose tokens to client-side code
  • ❌ Never commit tokens to version control
  • ❌ Never log tokens in plain text

Handling:

  • ✅ Implement automatic token refresh before expiration
  • ✅ Invalidate tokens when users log out or credentials change
  • ✅ Use HTTPS for all API calls
  • ❌ Never share tokens between environments (stage vs production)

Rotation:

  • ✅ Refresh tokens proactively (e.g., when 80% of TTL has elapsed)
  • ✅ Handle 401 errors gracefully with automatic retry after refresh
  • ✅ Implement circuit breakers for repeated auth failures

Example: Proactive Token Refresh

class TokenManager {
  private accessToken: string;
  private refreshToken: string;
  private expiresAt: number;

  async getValidToken(): Promise<string> {
    // Refresh if token expires in less than 5 minutes
    if (Date.now() > this.expiresAt - 5 * 60 * 1000) {
      await this.refresh();
    }
    return this.accessToken;
  }

  private async refresh(): Promise<void> {
    const response = await fetch(
      "https://na1-prod.okcapsule.app/v2/authentication/refresh-token",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ refresh_token: this.refreshToken }),
      }
    );
    const data = await response.json();
    this.accessToken = data.access_token;
    this.expiresAt = Date.now() + data.expires_in * 1000;
  }
}

Step 2: Make Your First Request​

Use the access token to make authenticated requests. Let's fetch your client products:

const response = await fetch(
  "https://na1-prod.okcapsule.app/v2/products",
  {
    headers: {
      Authorization: `Bearer ${access_token}`,
    },
  }
);

const { products } = await response.json();

Response:

{
  "client_products": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "product_name": "Vitamin D3",
      "active": true,
      "serving_size": 1
    }
  ]
}

Step 3: Create Your First Order​

Now let's create a simple order:

const order = {
  consumer: {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
  },
  shipping_address: {
    address1: "742 Evergreen Terrace",
    city: "Springfield",
    province_name: "Illinois",
    country_name: "United States",
    postal_code: "62701",
  },
  order_lines: [
    {
      duration: 30,
      pouches: [
        {
          time_of_administration: "Morning",
          contents: [
            {
              client_product_id: "d290f1ee-6c54-4b01-90e6-d701748f0851",
              serving_size: 1,
            },
          ],
        },
      ],
    },
  ],
};

const response = await fetch("https://na1-prod.okcapsule.app/v2/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(order),
});

const { order: createdOrder } = await response.json();

Response:

{
  "order": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "Pending",
    "consumer": {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Next Steps​

API Reference​

For complete endpoint documentation, visit the Interactive API Documentation.