The OpenCart REST API enables external applications to communicate with an OpenCart store for managing products, categories, orders, customers, manufacturers, and returns. Authentication uses API username/key credentials with IP-allowlist enforcement. Webhooks are supported for order creation, order updates, product sync, and customer registration events.
openapi: 3.0.3
info:
title: OpenCart REST API
description: >
The OpenCart REST API enables external applications to communicate with a
self-hosted OpenCart store. It provides endpoints for managing the shopping
cart, customers, orders, addresses, shipping methods, payment methods,
subscriptions, and affiliates. Authentication is performed by submitting API
credentials to receive a session token, which must accompany subsequent
requests. IP-allowlist enforcement is applied at the store level.
version: "4.0"
contact:
name: OpenCart Developer Documentation
url: https://docs.opencart.com/developer/
license:
name: GNU GPL v3
url: https://github.com/opencart/opencart/blob/master/LICENSE.md
externalDocs:
description: OpenCart Admin API Documentation
url: https://docs.opencart.com/admin-interface/system/users/api
servers:
- url: https://yourstore.com/index.php?route=api
description: OpenCart store API base URL (replace yourstore.com with your store domain)
security:
- apiToken: []
tags:
- name: Authentication
description: API login and session token management
- name: Cart
description: Shopping cart product management
- name: Customer
description: Customer session and profile management
- name: Orders
description: Order creation, confirmation, and history
- name: Payment Address
description: Billing address management
- name: Shipping Address
description: Shipping address management
- name: Shipping Methods
description: Available shipping method retrieval and selection
- name: Payment Methods
description: Available payment method retrieval and selection
- name: Subscriptions
description: Subscription order management
- name: Affiliates
description: Affiliate session management
paths:
/login:
post:
operationId: apiLogin
summary: Authenticate and obtain API session token
description: >
Submits API username and key credentials to authenticate. Returns a
session api_token that must be passed as a query parameter or POST field
on all subsequent requests. The calling IP address must be in the
store's API IP allowlist.
tags:
- Authentication
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- username
- key
properties:
username:
type: string
description: API username configured in Admin > System > Users > API
example: Default
key:
type: string
description: API key (64-character alphanumeric secret)
example: abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz12
responses:
"200":
description: Successful authentication
content:
application/json:
schema:
type: object
properties:
success:
type: string
description: Localised success message
example: "Success: You have modified APIs!"
api_token:
type: string
description: Session token to use for subsequent requests
example: 7a2f4e9c1d8b3f6a0e5c2d9b4f7a1e3c
"400":
description: Authentication failed (bad credentials or IP not allowed)
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/cart:
post:
operationId: addProductsToCart
summary: Add multiple products to cart
description: >
Adds one or more products to the shopping cart. Each product entry
may include required options and an optional subscription plan.
tags:
- Cart
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
api_token:
type: string
description: Session token from login
product:
type: array
items:
$ref: "#/components/schemas/CartProductInput"
responses:
"200":
description: Products added or validation errors returned
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/CartErrorResponse"
/cart/addProduct:
post:
operationId: addSingleProductToCart
summary: Add a single product to cart
description: >
Adds a single product to the shopping cart with full option and
subscription plan validation.
tags:
- Cart
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- product_id
properties:
api_token:
type: string
product_id:
type: integer
description: Product identifier
example: 28
quantity:
type: integer
description: Quantity to add (default 1)
default: 1
example: 2
option:
type: object
description: Map of option_id to option value(s)
additionalProperties:
oneOf:
- type: string
- type: array
items:
type: string
subscription_plan_id:
type: integer
description: Subscription plan ID (if adding as a subscription)
responses:
"200":
description: Product added or validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/CartErrorResponse"
/cart/getProducts:
get:
operationId: getCartProducts
summary: Retrieve cart products
description: Returns all products currently in the shopping cart session.
tags:
- Cart
parameters:
- $ref: "#/components/parameters/ApiToken"
responses:
"200":
description: Cart product list
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
$ref: "#/components/schemas/CartProduct"
/cart/getTotals:
get:
operationId: getCartTotals
summary: Retrieve cart totals
description: Returns formatted cart totals including subtotal, shipping, taxes, and grand total.
tags:
- Cart
parameters:
- $ref: "#/components/parameters/ApiToken"
responses:
"200":
description: Cart totals
content:
application/json:
schema:
type: object
properties:
totals:
type: array
items:
$ref: "#/components/schemas/CartTotal"
/customer:
post:
operationId: setCustomer
summary: Set customer for the current session
description: >
Associates a customer with the current API session. Validates customer
existence, group, name, email, telephone, and custom fields.
tags:
- Customer
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/CustomerInput"
responses:
"200":
description: Customer set or validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/CustomerErrorResponse"
/payment_address:
post:
operationId: setPaymentAddress
summary: Set payment (billing) address
description: >
Validates and stores the billing address for the current session.
Requires address fields including name, street, city, country, and zone.
tags:
- Payment Address
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/PaymentAddressInput"
responses:
"200":
description: Payment address set or validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/AddressErrorResponse"
/payment_address/setAddress:
post:
operationId: setPaymentAddressById
summary: Set payment address from saved customer address
description: Selects an existing saved customer address as the billing address.
tags:
- Payment Address
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- payment_address_id
properties:
api_token:
type: string
payment_address_id:
type: integer
description: ID of the saved customer address to use for billing
example: 5
responses:
"200":
description: Payment address set or error
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/ErrorResponse"
/shipping_address:
post:
operationId: setShippingAddress
summary: Set shipping (delivery) address
description: >
Validates and stores the shipping address for the current session.
Required when the cart contains shippable items.
tags:
- Shipping Address
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/ShippingAddressInput"
responses:
"200":
description: Shipping address set or validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ShippingAddressResponse"
- $ref: "#/components/schemas/AddressErrorResponse"
/shipping_method:
post:
operationId: setShippingMethod
summary: Set the shipping method for the order
description: >
Stores the selected shipping method in the session. Requires customer
and shipping address to be set, and that the cart has shippable items.
tags:
- Shipping Methods
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- shipping_method
properties:
api_token:
type: string
shipping_method:
$ref: "#/components/schemas/ShippingMethodInput"
responses:
"200":
description: Shipping method set or error
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/ErrorResponse"
/shipping_method/getShippingMethods:
get:
operationId: getShippingMethods
summary: Retrieve available shipping methods
description: >
Returns the list of available shipping methods for the current session.
Requires customer data and a shipping address to be set.
tags:
- Shipping Methods
parameters:
- $ref: "#/components/parameters/ApiToken"
responses:
"200":
description: Available shipping methods or error
content:
application/json:
schema:
oneOf:
- type: object
properties:
shipping_methods:
type: array
items:
$ref: "#/components/schemas/ShippingMethod"
- $ref: "#/components/schemas/ErrorResponse"
/payment_method:
post:
operationId: setPaymentMethod
summary: Set the payment method for the order
description: >
Stores the selected payment method in the session. Requires customer,
cart products, and if applicable, a payment address.
tags:
- Payment Methods
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- name
- code
properties:
api_token:
type: string
name:
type: string
description: Human-readable name of the payment method
example: Bank Transfer
code:
type: string
description: Machine code of the payment method
example: bank_transfer
responses:
"200":
description: Payment method set or error
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/ErrorResponse"
/payment_method/getPaymentMethods:
get:
operationId: getPaymentMethods
summary: Retrieve available payment methods
description: >
Returns the list of available payment methods for the current session.
Requires customer data, cart products, and if shipping is required,
a shipping address and method.
tags:
- Payment Methods
parameters:
- $ref: "#/components/parameters/ApiToken"
responses:
"200":
description: Available payment methods or error
content:
application/json:
schema:
oneOf:
- type: object
properties:
payment_methods:
type: array
items:
$ref: "#/components/schemas/PaymentMethod"
- $ref: "#/components/schemas/ErrorResponse"
/order:
post:
operationId: manageOrder
summary: Manage order operations via call parameter
description: >
Dispatches order operations based on the `call` query parameter.
Supports cart retrieval, product addition, address setting, shipping/payment
method selection, order confirmation, and history updates.
tags:
- Orders
parameters:
- name: call
in: query
required: true
schema:
type: string
enum:
- customer
- cart
- product_add
- payment_address
- shipping_address
- shipping_method
- shipping_methods
- payment_method
- payment_methods
- affiliate
- confirm
- history_add
description: The sub-operation to perform
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
api_token:
type: string
order_id:
type: integer
description: Required for confirm and history_add calls
order_status_id:
type: integer
description: Required for confirm and history_add calls
comment:
type: string
description: Optional comment for confirm or history_add
notify:
type: boolean
description: Whether to notify customer (history_add)
override:
type: boolean
description: Override stock check (history_add)
affiliate_id:
type: integer
description: Affiliate ID for confirm call
responses:
"200":
description: Operation result
content:
application/json:
schema:
type: object
description: Response varies by call parameter
properties:
success:
type: string
error:
type: string
order_id:
type: integer
/affiliate:
post:
operationId: setAffiliate
summary: Set affiliate for the current session
description: >
Associates an affiliate with the current API session. Validates that
the affiliate exists and that the order subtotal is valid.
tags:
- Affiliates
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
api_token:
type: string
affiliate_id:
type: integer
description: Affiliate ID (default 0 if not provided)
example: 3
responses:
"200":
description: Affiliate set or error
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SuccessResponse"
- $ref: "#/components/schemas/ErrorResponse"
/subscription:
post:
operationId: manageSubscription
summary: Manage subscription order operations via call parameter
description: >
Dispatches subscription operations based on the `call` query parameter.
Supports cart retrieval, product addition, shipping/payment method
selection, order confirmation, and history updates for subscription orders.
tags:
- Subscriptions
parameters:
- name: call
in: query
required: true
schema:
type: string
enum:
- cart
- product_add
- shipping_methods
- payment_methods
- confirm
- history_add
description: The sub-operation to perform
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
api_token:
type: string
customer_id:
type: integer
description: Customer identifier
payment_address_id:
type: integer
description: Saved address ID for billing
shipping_address_id:
type: integer
description: Saved address ID for delivery
subscription_id:
type: integer
description: Existing subscription ID
subscription_plan_id:
type: integer
description: Subscription plan ID
subscription_status_id:
type: integer
description: Subscription status (for history_add)
comment:
type: string
notify:
type: boolean
responses:
"200":
description: Operation result
content:
application/json:
schema:
type: object
properties:
success:
type: string
error:
type: string
components:
securitySchemes:
apiToken:
type: apiKey
in: query
name: api_token
description: Session token obtained from the /login endpoint
parameters:
ApiToken:
name: api_token
in: query
required: true
schema:
type: string
description: Session token from the login endpoint
schemas:
SuccessResponse:
type: object
properties:
success:
type: string
description: Localised success message
example: "Success: You have modified your shopping cart!"
ErrorResponse:
type: object
properties:
error:
type: string
description: Localised error message
example: "Warning: Permission Denied!"
CartErrorResponse:
type: object
properties:
error:
type: object
properties:
warning:
type: string
product:
type: string
option:
type: string
subscription:
type: string
CustomerErrorResponse:
type: object
properties:
error:
type: object
properties:
warning:
type: string
customer_group:
type: string
firstname:
type: string
lastname:
type: string
email:
type: string
telephone:
type: string
AddressErrorResponse:
type: object
properties:
error:
type: object
properties:
firstname:
type: string
lastname:
type: string
address_1:
type: string
city:
type: string
postcode:
type: string
country:
type: string
zone:
type: string
CartProductInput:
type: object
required:
- product_id
- quantity
properties:
product_id:
type: integer
example: 28
quantity:
type: integer
default: 1
example: 1
option:
type: object
additionalProperties:
oneOf:
- type: string
- type: array
items:
type: string
subscription_plan_id:
type: integer
CartProduct:
type: object
properties:
cart_id:
type: string
product_id:
type: integer
name:
type: string
model:
type: string
option:
type: array
items:
type: object
properties:
product_option_id:
type: integer
product_option_value_id:
type: integer
name:
type: string
value:
type: string
type:
type: string
subscription_plan_id:
type: integer
subscription:
type: string
description: Formatted subscription description
quantity:
type: integer
price:
type: number
format: float
total:
type: number
format: float
CartTotal:
type: object
properties:
title:
type: string
description: Display label (e.g. Sub-Total, Flat Shipping Rate, Tax, Total)
example: "Sub-Total"
text:
type: string
description: Formatted currency value
example: "$100.00"
value:
type: number
format: float
example: 100.0
CustomerInput:
type: object
required:
- customer_id
- customer_group_id
- firstname
- lastname
- email
properties:
api_token:
type: string
customer_id:
type: integer
example: 1
customer_group_id:
type: integer
example: 1
firstname:
type: string
maxLength: 32
example: John
lastname:
type: string
maxLength: 32
example: Doe
email:
type: string
format: email
example: [email protected]
telephone:
type: string
minLength: 3
maxLength: 32
example: "+1 555-0100"
custom_field:
type: object
additionalProperties: true
PaymentAddressInput:
type: object
required:
- payment_firstname
- payment_lastname
- payment_address_1
- payment_city
- payment_country_id
- payment_zone_id
properties:
api_token:
type: string
payment_firstname:
type: string
minLength: 1
maxLength: 32
example: John
payment_lastname:
type: string
minLength: 1
maxLength: 32
example: Doe
payment_company:
type: string
example: ACME Corp
payment_address_1:
type: string
minLength: 3
maxLength: 128
example: "123 Main Street"
payment_address_2:
type: string
example: "Suite 100"
payment_postcode:
type: string
minLength: 2
maxLength: 10
example: "90210"
payment_city:
type: string
minLength: 2
maxLength: 128
example: "Los Angeles"
payment_zone_id:
type: integer
example: 3635
payment_country_id:
type: integer
example: 223
payment_custom_field:
type: object
additionalProperties: true
ShippingAddressInput:
type: object
required:
- shipping_firstname
- shipping_lastname
- shipping_address_1
- shipping_city
- shipping_country_id
- shipping_zone_id
properties:
api_token:
type: string
shipping_firstname:
type: string
minLength: 1
maxLength: 32
example: John
shipping_lastname:
type: string
minLength: 1
maxLength: 32
example: Doe
shipping_company:
type: string
shipping_address_1:
type: string
minLength: 3
maxLength: 128
example: "456 Elm Street"
shipping_address_2:
type: string
shipping_postcode:
type: string
minLength: 2
maxLength: 10
example: "90210"
shipping_city:
type: string
minLength: 2
maxLength: 128
example: "Los Angeles"
shipping_country_id:
type: integer
example: 223
shipping_zone_id:
type: integer
example: 3635
shipping_custom_field:
type: object
additionalProperties: true
ShippingAddressResponse:
type: object
properties:
success:
type: string
shipping_address:
$ref: "#/components/schemas/Address"
ShippingMethodInput:
type: object
required:
- name
- code
- cost
- tax_class_id
properties:
name:
type: string
description: Human-readable name of the shipping method
example: "Flat Shipping Rate"
code:
type: string
description: Machine code of the shipping method
example: "flat.flat"
cost:
type: number
format: float
description: Shipping cost (pre-tax)
example: 5.00
tax_class_id:
type: integer
description: Tax class applied to shipping cost
example: 9
ShippingMethod:
type: object
properties:
title:
type: string
example: "Flat Shipping Rate"
quote:
type: object
additionalProperties:
type: object
properties:
code:
type: string
name:
type: string
cost:
type: number
format: float
tax_class_id:
type: integer
text:
type: string
sort_order:
type: integer
error:
type: string
PaymentMethod:
type: object
properties:
code:
type: string
example: "bank_transfer"
name:
type: string
example: "Bank Transfer"
sort_order:
type: integer
example: 1
Address:
type: object
properties:
address_id:
type: integer
firstname:
type: string
lastname:
type: string
company:
type: string
address_1:
type: string
address_2:
type: string
postcode:
type: string
city:
type: string
zone_id:
type: integer
zone:
type: string
zone_code:
type: string
country_id:
type: integer
country:
type: string
iso_code_2:
type: string
iso_code_3:
type: string
address_format:
type: string
custom_field:
type: object
additionalProperties: true