Skip to main content

Recommended Integration Flow

Start with a successful signed request. Use the identifiers returned in the response for subsequent requests, and follow the recovery guidance for your integration.

  1. 1
    Create an API key and store credentials securely. Follow Authentication.
  2. 2
    Choose the scopes required for your integration when creating the API key.
  3. 3
    Send a signed request to retrieve your default partner link and confirm that your credentials and read access work.
  4. 4
    Apply the shared partner request budget and the operation settings from API Configuration and Limits before starting recurring requests or exports.
  5. 5
    Choose what you want to build: manage campaigns, retrieve reports, check rebate payments, manage referral-agent links, or monitor your partner tier. Open the corresponding guide for the next steps.
  6. 6
    If your workflow requires creating a campaign or referral-agent link, save the identifier returned in the response. Use it in subsequent requests to retrieve or update that resource.
  7. 7
    Keep filters and ordering unchanged while paging through reports. Re-read recent data when reconciling asynchronous results.
  8. 8
    Handle errors by their HTTP status and machine-readable code. After an unknown write outcome, read current state before deciding whether to repeat the write.

Example pseudo-code​

Conceptual pseudo-code; signed_request, storage and application decisions must be implemented by your integration.

credentials = load_credentials_from_secure_backend_storage()
link = signed_request(GET, /v1/partnership/partner/default-link)
existing_campaigns = signed_request(GET, /v1/partnership/campaigns)
if application_requires_a_new_campaign:
    try:
        campaign = signed_request(POST, /v1/partnership/campaigns, campaign_input)
        store(campaign.campaign_code)
    on timeout_or_connection_loss:
        campaigns = signed_request(GET, /v1/partnership/campaigns)
        reconcile_with_the_intended_change(campaigns)
        require_a_decision_before_another_create()

Decision points​

SituationNext action
You only need reports or rebate resultsUse partnership.all:read for reads. Use partnership.all if you also need to change rebate settings.
You need to create a campaign or referral-agent linkUse partnership.all. Check the operation’s required fields and restrictions in API Reference before sending the request.
A write times out or its response is lostRead the resource or its list and compare the returned state with your intended change. If the outcome remains unclear, do not automatically repeat the write. This API provides no idempotent-write guarantee.
A report does not yet reflect a recent changeRe-read the affected report with the same filters. Keep filters and ordering unchanged while paging. Reports update asynchronously; pages and report families do not share a guaranteed snapshot.
A rebate batch is PROCESSEDInspect rejected amounts and individual row statuses. A completed batch does not mean every row was paid. See Rebates.
You need shared-report data or different referral-agent termsThese operations are not available in this API version. Referral-agent responses expose the current terms and shared-report configuration only.
A read receives a temporary error or rate limitFollow the retry rule for the returned error code in Troubleshooting. Use backoff where instructed and honor Retry-After when returned. Generate a fresh timestamp and signature for each retry.