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.

Quick Start Checklist​

Before you can create orders, ensure you have:

  • API credentials - Email and password from your OK Capsule account representative
  • Environment access - Know which environment you're using (Stage for testing, Production for live orders)
  • 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({
      email: "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 products:

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

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

Response:

{
  "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.