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: john.doe@example.com
        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