Cardlytics

Cardlytics Partner API

The advertiser-partner integration surface. Partners upsert and delete merchants and offers keyed on their own external identifiers, pull aggregate merchant/offer performance metrics (impressions, purchases, revenue, reach, activations), and fetch a pre-signed URL for the daily redemption feed. OAuth 2.0 client credentials; 7 operations across 5 paths.

GitHub OpenAPI

Documentation

📖
Documentation
https://platform.cardlytics.com/advertisers/docs/api-get-started
📖
APIReference
https://platform.cardlytics.com/advertisers/reference
📖
GettingStarted
https://platform.cardlytics.com/advertisers/docs/api-get-started

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cardlytics/refs/heads/main/openapi/cardlytics-partner-api-openapi.yml
⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cardlytics/refs/heads/main/openapi/_original/cardlytics-partner-api-openapi.json

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/cardlytics/refs/heads/main/overlays/cardlytics-partner-api-overlay.yaml
🔗
Sandbox
https://api-sandbox.cardlytics.com
🔗
ChangeLog
https://platform.cardlytics.com/advertisers/changelog
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/cardlytics/refs/heads/main/apis.yml

OpenAPI Specification

cardlytics-partner-api-openapi.yml Raw ↑ 
openapi: 3.0.1
info:
  title: partner-api
  description: Partner APIs
  version: '2025-10-07'
servers:
- url: https://api-sandbox.cardlytics.com
  description: Sandbox environment - Use this for API testing and development
- url: https://api.cardlytics.com
  description: Production environment - Documentation reference only, contact support for access
paths:
  /api/v1/idp/oauth2/token:
    post:
      summary: Generate OAuth2 access token
      description: Obtain an access token using client credentials for API authentication
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                  description: Must be 'client_credentials'
                client_id:
                  type: string
                  description: Your client ID
                client_secret:
                  type: string
                  description: Your client secret
              required:
              - grant_type
              - client_id
              - client_secret
      responses:
        '200':
          description: Token generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: The access token
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    description: Token expiration time in seconds
        '400':
          description: Bad Request - Invalid parameters
        '401':
          description: Unauthorized - Invalid client credentials
  /api/v1/partner/merchants/{external_merchant_id}:
    put:
      summary: Create or Update the Merchant using the partner-provided merchant ID
      description: Create or update merchant information. The external_merchant_id in the path must match the merchantId in
        the request body.
      tags:
      - Merchants
      parameters:
      - name: external_merchant_id
        in: path
        description: Partner-provided merchant identifier
        required: true
        schema:
          type: string
          default: '67890'
        example: '67890'
      requestBody:
        description: Merchant object that needs to be inserted or updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantPayload'
            example:
              merchantId: '67890'
              merchantName: Tony's Grill & Bar
              merchantCategoryCode: 5812
              merchantUrl: www.tonysgrill.com
              merchantSubCategories:
              - categoryType: cuisine
                categoryItems:
                - American
                - BBQ
                - Steakhouse
              paymentChannels:
              - instore
              stores:
              - storeId: '2047'
                storeName: Tony's Grill Downtown
                storeUrl: www.tonysgrill.com/downtown
                address1: 456 Broadway Ave
                address2: Suite 101
                city: SPRINGFIELD
                state: IL
                postalCode: '62701'
                countryCode: US
                latitude: '39.8017'
                longitude: '-89.6437'
                storePhoneNumbers:
                - '+12175559876'
                storeEmails:
                - info@tonysgrill.com
                processorMidChangedFlag: N
                processorMidRecords:
                - paymentNetwork: AmericanExpress
                  processors:
                  - processorName: AmericanExpress
                    amexMids:
                    - seNumber: '9876543210'
                - paymentNetwork: MasterCard
                  processors:
                  - processorName: Chase Paymentech
                    mcAuthMids:
                    - mcAuthLocationId: '556677888'
                      mcAuthAcquiringMid: '999888777666555'
                      mcAuthICA: 098765
                    mcClearingMids:
                    - mcClearingLocationId: '445566777'
                      mcClearingAcquiringMid: '888777666555444'
                      mcClearingICA: 087654
                - paymentNetwork: Visa
                  processors:
                  - processorName: First Data
                    processorId: FD789
                    visaMids:
                    - vmid: '87651234'
                      vsid: '44332211'
                  - processorName: Global Payments
                    processorId: GP456
                    visaMids:
                    - vmid: '13579246'
                      vsid: '66554433'
                - paymentNetwork: Discover
                  processors:
                  - processorName: Discover
                    discoverMids:
                    - discover: '7774032918456'
                    - discover: '7774051297384'
      responses:
        '202':
          description: Added to the queue for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceResponse'
        '400':
          description: "Bad Request – possible client errors:\n  - Invalid input (schema validation failure)  \n  - ID mismatch\n"
        '500':
          description: Internal Server Error – An unexpected error occurred while processing the request
    delete:
      summary: Delete the Merchant using the partner-provided merchant ID
      tags:
      - Merchants
      parameters:
      - name: external_merchant_id
        in: path
        description: Partner-provided merchant identifier
        required: true
        schema:
          type: string
          default: '67890'
        example: '67890'
      responses:
        '202':
          description: Accepted and queued for deletion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceResponse'
        '400':
          description: 'Bad Request – ID mismatch

            '
        '500':
          description: Internal Server Error – An unexpected error occurred while processing the request
  /api/v1/partner/merchants/{external_merchant_id}/offers/{external_offer_id}:
    put:
      summary: Create or Update the Offer using the partner-provided merchant ID and offer ID
      description: 'Create or update offer information. The external_merchant_id and external_offer_id in the path must match
        the merchantId and offerId in the request body respectively.


        **Note**: If you don''t have a separate offer identifier, you can use the external_merchant_id as the external_offer_id.

        '
      tags:
      - Offers
      parameters:
      - name: external_merchant_id
        in: path
        description: Partner's unique identifier of their Merchant as shared in the Merchant feed
        required: true
        schema:
          type: string
          default: '67890'
        example: '67890'
      - name: external_offer_id
        in: path
        description: Partner's unique Offer Id for the Merchant. If you don't have a separate offer identifier, you can use
          the same value as external_merchant_id.
        required: true
        schema:
          type: string
          default: OFFER-001
        example: OFFER-001
      requestBody:
        description: Offer object that needs to be inserted or updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferPayload'
            example:
              offerId: OFFER-001
              merchantId: '67890'
              offerName: Tony's Grill
              assets:
                logo:
                  type: IMAGE
                  value:
                    large:
                      url: https://picsum.photos/627/627?random=1
                largeRectangle:
                  type: IMAGE
                  value:
                    large:
                      url: https://picsum.photos/1200/627?random=1
      responses:
        '202':
          description: Accepted and queued for campaign creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceResponse'
        '400':
          description: "Bad Request – possible client errors:\n  - Invalid input (schema validation failure)  \n  - ID mismatch\n"
        '500':
          description: Internal Server Error – An unexpected error occurred while processing the request
    delete:
      summary: Delete the Offer using the partner-provided offer ID and merchant ID
      description: 'Delete an offer using the partner-provided identifiers.


        **Note**: If you don''t have a separate offer identifier, you can use the external_merchant_id as the external_offer_id.

        '
      tags:
      - Offers
      parameters:
      - name: external_merchant_id
        in: path
        description: Partner's unique identifier of their Merchant as shared in the Merchant feed
        required: true
        schema:
          type: string
          default: '67890'
        example: '67890'
      - name: external_offer_id
        in: path
        description: Partner's unique Offer Id for the Merchant. If you don't have a separate offer identifier, you can use
          the same value as external_merchant_id.
        required: true
        schema:
          type: string
          default: OFFER-001
        example: OFFER-001
      responses:
        '202':
          description: Accepted and queued for deletion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceResponse'
        '400':
          description: 'Bad Request – ID mismatch

            '
        '500':
          description: Internal Server Error – An unexpected error occurred while processing the request
  /api/v1/partner/merchants/{external_merchant_id}/reports:
    post:
      summary: Get merchant performance report (aggregate metrics)
      description: 'Returns aggregated performance metrics for a partner-provided merchant over a date range. Supports optional
        filtering by offer IDs. Defaults: cube=merchant_performance; timeRange.from defaults to 2 years back (max lookback);
        timeRange.to defaults to today''s date.'
      tags:
      - Reports
      parameters:
      - name: external_merchant_id
        in: path
        description: Partner-provided merchant identifier
        required: true
        schema:
          type: string
          default: '67890'
        example: '67890'
      requestBody:
        required: true
        description: 'Optional filters. If `offerIds` is omitted or empty, metrics are returned for all offers under the merchant.
          `cube` currently supports only `merchant_performance`. `timeRange` is optional: `from` defaults to 2 years back
          (max lookback) and `to` defaults to today''s date (YYYY-MM-DD).'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
            example:
              cube: merchant_performance
              offerIds: []
              timeRange:
                from: '2023-10-01'
                to: '2025-09-17'
      responses:
        '200':
          description: Aggregated performance for offers under the merchant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
              example:
                header:
                  cube: merchant_performance
                  fields:
                  - fieldName: Partner Merchant Id
                    fieldType: DIM
                  - fieldName: Partner Offer Id
                    fieldType: DIM
                  - fieldName: Impressions
                    fieldType: FACT
                  - fieldName: Purchases
                    fieldType: FACT
                  - fieldName: Revenue
                    fieldType: FACT
                  - fieldName: Reach
                    fieldType: FACT
                  - fieldName: Activations
                    fieldType: FACT
                  maxRows: -1
                rows:
                - - 88d4d968-e922-sample-partner-merchant-id-f32a0eaa43ff
                  - 2e1fd66d-72d7-sample-partner-offer-id-af82-b4bfd0aaa7ac
                  - 280568
                  - 14
                  - 714.87
                  - 172472
                  - 8005
                - - 88d4d968-e922-sample-partner-merchant-id-f32a0eaa43ff
                  - 5555d66d-72d7-sample-partner-offer-id-af82-343430aaa7ac
                  - 100568
                  - 8
                  - 14.22
                  - 2472
                  - 807
        '400':
          description: Bad Request – Invalid parameters or date range.
        '401':
          description: Unauthorized – Invalid or missing access token.
        '500':
          description: Internal Server Error – An unexpected error occurred while processing the request.
  /api/v1/partner/redemptions:
    get:
      summary: Get daily redemptions pre-signed URL
      description: Returns a pre-signed URL to download all redemptions for a specific day. The day must be in the past (UTC
        time). The pre-signed URL is valid for 60 minutes only.
      tags:
      - Redemptions
      parameters:
      - name: date
        in: query
        description: 'The date for which to retrieve redemptions (format: YYYY-MM-DD, must be a past date and not today or
          in the future).'
        required: true
        schema:
          type: string
          format: date
          example: '2026-01-04'
      responses:
        '200':
          description: Pre-signed URL generated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: The pre-signed URL to download the redemptions file.
                required:
                - url
        '400':
          description: Bad Request - The date format is incorrect, or the date is today's date or in the future.
        '500':
          description: Internal Server Error - An unexpected error occurred.
components:
  schemas:
    TraceResponse:
      type: object
      description: Response containing the trace identifier
      properties:
        message:
          type: string
          example: Message description of the operation
        trace_id:
          type: string
          description: Request trace identifier
      required:
      - message
      - trace_id
    ReportRequest:
      type: object
      description: Request to retrieve aggregated performance per offer for a merchant.
      properties:
        cube:
          type: string
          description: Reporting cube to query. Only 'merchant_performance' is currently supported.
          enum:
          - merchant_performance
          default: merchant_performance
        offerIds:
          type: array
          description: Optional list of partner offer IDs to filter. Empty or omitted returns all offers for the merchant.
          items:
            type: string
        timeRange:
          type: object
          description: 'Inclusive date range for the report (YYYY-MM-DD). If omitted: `from` defaults to 2 years back (max
            lookback) and `to` defaults to today''s date.'
          properties:
            from:
              type: string
              format: date
              description: Start date (inclusive).
            to:
              type: string
              format: date
              description: End date (inclusive).
          required:
          - from
          - to
    ReportField:
      type: object
      description: A field in the report header describing a dimension or metric.
      properties:
        fieldName:
          type: string
        fieldType:
          type: string
          enum:
          - DIM
          - FACT
      required:
      - fieldName
      - fieldType
    ReportHeader:
      type: object
      description: Metadata describing the report payload.
      properties:
        cube:
          type: string
          description: Logical data source (e.g., cube or dataset). Only 'merchant_performance' is currently supported.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ReportField'
        maxRows:
          type: integer
          description: Maximum number of rows returned; -1 means no limit.
          default: -1
      required:
      - cube
      - fields
      - maxRows
    ReportResponse:
      type: object
      description: Aggregated report response with a header and data rows.
      properties:
        header:
          $ref: '#/components/schemas/ReportHeader'
        rows:
          type: array
          description: Tabular results; each row aligns with the header fields order.
          items:
            type: array
            items:
              oneOf:
              - type: string
              - type: number
              - type: integer
      required:
      - header
      - rows
    OfferPayload:
      type: object
      description: A partner offer payload
      properties:
        offerId:
          type: string
          description: Partner’s unique Offer Id for the Merchant
        merchantId:
          type: string
          description: Partner’s unique identifier of their Merchant as shared in the Merchant feed
        offerName:
          type: string
          description: Offer Name
        assets:
          type: object
          description: 'Two image assets (logo and largeRectangle).

            '
          properties:
            logo:
              $ref: '#/components/schemas/ImageAsset'
              description: Logo image asset (627x627)
            largeRectangle:
              $ref: '#/components/schemas/ImageAsset'
              description: Large rectangle image asset (1200x627)
          required:
          - logo
          - largeRectangle
      required:
      - offerId
      - merchantId
      - offerName
      - assets
    ImageAsset:
      type: object
      description: An image asset with type and a single `large` payload
      properties:
        type:
          type: string
          enum:
          - IMAGE
          description: Must be 'IMAGE'
        value:
          type: object
          description: Wrapper for the actual image payload
          properties:
            large:
              $ref: '#/components/schemas/LargeImage'
          required:
          - large
      required:
      - type
      - value
    LargeImage:
      type: object
      description: 'The full-sized image. Exactly one of `url` or `content` must be present.

        '
      properties:
        url:
          type: string
          format: uri
          description: URL to the image
        content:
          type: string
          description: 'Data URL form of the image string (e.g., `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA`). Refer
            to RFC 2397 for details.

            '
      oneOf:
      - required:
        - url
      - required:
        - content
    MerchantPayload:
      type: object
      properties:
        merchantId:
          type: string
          minLength: 1
          description: Partner-provided merchant identifier
        merchantName:
          type: string
          minLength: 1
          description: Registered name of the merchant or brand
        parentMerchantId:
          type: string
          description: Any Parent of this merchant
        merchantCategoryCode:
          type: number
          description: ISO 18245 4-digit MCC code
        merchantSubCategories:
          type: array
          description: List of merchant sub-category objects
          items:
            type: object
            properties:
              categoryType:
                type: string
                description: 'Ex: Cuisine'
              categoryItems:
                type: array
                description: Sub-category values (no special characters)
                items:
                  type: string
            required:
            - categoryType
            - categoryItems
        paymentChannels:
          type: array
          description: Indicates if this merchant accepts payments online or instore
          items:
            type: string
            enum:
            - online
            - instore
            minLength: 1
          minItems: 1
        paymentSubChannels:
          type: array
          description: Payment sub-channels (PayAtPump or Convenience)
          items:
            type: string
            enum:
            - PayAtPump
            - Convenience
        merchantUrl:
          type: string
          description: Merchant Website URL
        merchantApps:
          type: array
          description: List of Online Apps used by Merchant
          items:
            type: string
        stores:
          type: array
          description: One or more store objects for this merchant
          items:
            type: object
            properties:
              storeId:
                type: string
                minLength: 1
                description: Partner-provided store identifier
              address1:
                type: string
                minLength: 1
                description: Street Address
              address2:
                type: string
                description: Street Address (optional)
              city:
                type: string
                minLength: 1
              state:
                type: string
                minLength: 1
              postalCode:
                type: string
                minLength: 1
              countryCode:
                type: string
                minLength: 1
                description: 2-character country code (ISO 3166-1 alpha-2)
              storeName:
                type: string
                minLength: 1
                description: Name of the store
              locatedIn:
                type: string
                description: Business or venue the merchant is inside
              storePhoneNumbers:
                type: array
                description: List of phone numbers of the store
                items:
                  type: string
              storeUrl:
                type: string
                description: Store Website URL
              storeEmails:
                type: array
                description: List of business email of the store
                items:
                  type: string
              latitude:
                type: string
                description: The latitude coordinates of the merchant store location
              longitude:
                type: string
                description: The longitude coordinates of the merchant store location
              processorMidChangedFlag:
                type: string
                minLength: 1
                description: Y=Yes, N=No
                enum:
                - Y
                - N
              processorMidRecords:
                type: array
                description: List of processor MID records
                items:
                  type: object
                  properties:
                    paymentNetwork:
                      type: string
                      enum:
                      - Visa
                      - MasterCard
                      - AmericanExpress
                      - Discover
                      description: Payment network for this MID record
                    processors:
                      type: array
                      minItems: 1
                      description: List of processor details for this payment network
                      items:
                        type: object
                        properties:
                          processorName:
                            type: string
                            minLength: 1
                            description: Name of the processor. When not available use “UNKNOWN”
                          processorId:
                            type: string
                            description: processor ID
                          amexMids:
                            type: array
                            description: paymentNetwork=AmericanExpress, "amexMids" array must contain at least one "seNumber"
                              in the array
                            items:
                              type: object
                              properties:
                                seNumber:
                                  type: string
                                  minLength: 1
                                  description: SE Number for Amex
                          visaMids:
                            type: array
                            description: paymentNetwork=VISA, "visaMids" array must contain at least one element with both
                              "vmid" and "vsid"
                            items:
                              type: object
                              properties:
                                vmid:
                                  type: string
                                  minLength: 1
                                  description: Visa MID
                                vsid:
                                  type: string
                                  minLength: 1
                                  description: Visa SID
                          mcAuthMids:
                            type: array
                            description: paymentNetwork=MasterCard, at least one of the "mcAuthMids" array field or "mcClearingMids"
                              array field is present
                            items:
                              type: object
                              properties:
                                mcAuthLocationId:
                                  type: string
                                  minLength: 1
                                  description: MasterCard Auth Location ID. Required for mcAuthMids
                                mcAuthAcquiringMid:
                                  type: string
                                  minLength: 1
                                  description: MasterCard Auth Acquiring MID. Required for mcAuthMids
                                mcAuthICA:
                                  type: string
                                  description: MasterCard Auth ICA (optional)
                          mcClearingMids:
                            type: array
                            description: paymentNetwork=MasterCard, at least one of the "mcAuthMids" array field or "mcClearingMids"
                              array field is present
                            items:
                              type: object
                              properties:
                                mcClearingLocationId:
                                  type: string
                                  minLength: 1
                                  description: MasterCard Clearing Location ID. Required for mcClearingMids
                                mcClearingAcquiringMid:
                                  type: string
                                  minLength: 1
                                  description: MasterCard Clearing Acquiring MID. Required for mcClearingMids
                                mcClearingICA:
                                  type: string
                                  description: MasterCard Clearing ICA (optional)
                          discoverMids:
                            type: array
                            description: paymentNetwork=Discover, "discoverMids" array must contain at least one "discover"
                              in the array
                            items:
                              type: object
                              properties:
                                discover:
                                  type: string
                                  minLength: 1
                                  description: Discover MID
                        required:
                        - processorName
                  required:
                  - paymentNetwork
                  - processors
                minItems: 1
            required:
            - storeId
            - address1
            - city
            - state
            - postalCode
            - countryCode
            - storeName
            - processorMidChangedFlag
            - processorMidRecords
            minProperties: 1
          minItems: 1
      required:
      - merchantId
      - merchantName
      - paymentChannels
      - stores
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /v1/idp/oauth2/token
          scopes:
            openid: openid
security:
- oauth2:
  - openid
x-readme:
  explorer-enabled: true
  proxy-enabled: true