Skip to content

Corksy API (1.2.0)

API for retrieving orders, customers, inventory, wine-club data, and products.

Authentication

This API uses a two-step authentication process:

Step 1: Generate API Key

First, generate your API key from the Admin Settings API page:

  • Go to: https://admin.corksy.io/settings/apiaccess
  • Create a new API key for your application

Step 2: Obtain Bearer Token

Use your API key to obtain a bearer token by making a POST request to the authentication endpoint:

Production:

curl --location 'https://connect-api.corksy.io/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'

Staging:

curl --location 'https://staging.corksy.io/connect-api/v1/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'

Response:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 1800000
}

Step 3: Use Bearer Token

Use the accessToken from the response as a Bearer token in the Authorization header for all subsequent API requests:

Example Requests:

Get Orders:

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Customers:

curl --location 'https://connect-api.corksy.io/v1/customers' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Inventory:

curl --location 'https://connect-api.corksy.io/v1/inventory' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Wine Clubs:

curl --location 'https://connect-api.corksy.io/v1/wine-clubs' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Wine Club Members:

curl --location 'https://connect-api.corksy.io/v1/wine-club-members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Products:

curl --location 'https://connect-api.corksy.io/v1/products?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Note: The bearer token expires after 30 minutes (1,800,000 microseconds). You'll need to obtain a new token when it expires.

Pagination

All list endpoints support pagination to handle large datasets efficiently. The API uses offset-based pagination with the following parameters:

Pagination Parameters

  • offset (optional): Number of records to skip. Default: 0
  • pageSize (optional): Number of records to return per page. Default: 1000, Maximum: 1000

Pagination Response

Each paginated response includes a pagination object with the following information:

{
  "data": [...],
  "pagination": {
    "current_offset": 0,
    "page_size": 50,
    "total_records": 1250,
    "total_pages": 25,
    "current_page": 1,
    "pages_remaining": 24,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Pagination Examples

First Page (Default):

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer YOUR_TOKEN'

Second Page (50 records per page):

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&offset=50&pageSize=50' \
--header 'Authorization: Bearer YOUR_TOKEN'

Custom Page Size:

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&pageSize=100' \
--header 'Authorization: Bearer YOUR_TOKEN'

Best Practices

  1. Start with the first page (no parameters or offset=0)
  2. Use has_next_page to determine if more pages exist
  3. Increment offset by page_size to get the next page
  4. Choose appropriate page_size based on your needs.
  5. Handle rate limits - each page request counts toward your rate limit
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Staging Environment
https://staging.corksy.io/connect-api/v1/
Production Environment
https://connect-api.corksy.io/

Authentication

Endpoints related to authentication and authorization

Operations

Orders

Endpoints related to orders

Operations

Retrieve a list of orders within a date range

Request

🚦 Rate Limit: 100 requests / minute

Security
BearerAuth
Query
modifiedFromDatestring(date-time)

Filter orders modified from this date (ISO 8601 format). If specified without modifiedToDate, current date will be used as end date.

Example: modifiedFromDate=2025-05-01T00:00:00Z
modifiedToDatestring(date-time)

Filter orders modified up to this date (ISO 8601 format). Cannot be specified without modifiedFromDate.

Example: modifiedToDate=2025-05-31T23:59:59Z
offsetinteger>= 0

Number of records to skip for pagination (default: 0)

Example: offset=0
pageSizeinteger[ 1 .. 1000 ]

Number of records to return per page (default: 1000, max: 1000)

Example: pageSize=50
curl -i -X GET \
  'https://staging.corksy.io/connect-api/v1/orders?modifiedFromDate=2025-05-01T00%3A00%3A00Z&modifiedToDate=2025-05-31T23%3A59%3A59Z&offset=0&pageSize=50' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A list of orders within the specified date range

Bodyapplication/json
dataArray of objects(Order)
paginationobject(PaginationInfo)
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "current_offset": 0,
    "page_size": 50,
    "total_records": 1250,
    "total_pages": 25,
    "current_page": 1,
    "pages_remaining": 24,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Customers

Endpoints related to customers

Operations

Inventory

Endpoints related to inventory

Operations

Wine Clubs

Endpoints related to wine clubs

Operations

Wine Club Members

Endpoints related to wine-club members

Operations

Products

Endpoints related to products

Operations