> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate with AI assistance

> Copy-paste prompts for AI coding assistants to integrate Partnero into your application. Works with Cursor, GitHub Copilot, ChatGPT, Claude, and other AI tools.

These are ready-to-use prompts you can paste into AI coding assistants like Cursor, GitHub Copilot, ChatGPT, or Claude. Each prompt includes the API context the AI needs to generate correct, working code for your Partnero integration.

## How to use

1. Pick the prompt that matches your integration scenario
2. Copy it and paste it into your AI coding assistant
3. Replace `YOUR_API_KEY` and `YOUR_PROGRAM_ID` with your actual values from the [Partnero dashboard](https://app.partnero.com)
4. Add a line describing your tech stack (e.g., "I'm using Next.js 14 with App Router, Prisma, and NextAuth")
5. If possible, point the AI to your existing sign-up or payment code so it knows where to add the integration

## Affiliate program

### Full affiliate tracking

<Accordion title="Prompt: Add affiliate tracking to my app">
  ```text theme={null}
  Integrate Partnero affiliate tracking into my application.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  Context about Partnero:
  - Partnero is an affiliate/partner management platform
  - API base URL: https://api.partnero.com/v1/
  - Authentication: Bearer token in Authorization header
  - API key: YOUR_API_KEY
  - Program ID: YOUR_PROGRAM_ID

  What needs to happen:

  1. FRONTEND — Add this PartneroJS snippet before </head> on all pages:
  <script>
      (function(p,t,n,e,r,o){ p['__partnerObject']=r;function f(){
      var c={ a:arguments,q:[]};var r=this.push(c);return "number"!=typeof r?r:f.bind(c.q);}
      f.q=f.q||[];p[r]=p[r]||f.bind(f.q);p[r].q=p[r].q||f.q;o=t.createElement(n);
      var _=t.getElementsByTagName(n)[0];o.async=1;o.src=e+'?v'+(~~(new Date().getTime()/1e6));
      _.parentNode.insertBefore(o,_);})(window, document, 'script', 'https://app.partnero.com/js/universal.js', 'po');
      po('settings', 'assets_host', 'https://assets.partnero.com');
      po('program', 'YOUR_PROGRAM_ID', 'load');
  </script>
  This script reads the partner key from referral URLs (e.g., ?ref=PARTNER_KEY)
  and stores it in a "partnero_partner" first-party cookie.

  2. BACKEND — In my existing sign-up/registration handler, read the
  "partnero_partner" cookie from the HTTP request and call:
  POST https://api.partnero.com/v1/customers
  Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
  Body:
  {
    "partner": { "key": "VALUE_FROM_COOKIE" },
    "key": "unique_customer_id",
    "email": "customer@example.com",
    "name": "Customer Name"
  }

  3. BACKEND — In my existing payment/checkout handler, after a successful
  payment call:
  POST https://api.partnero.com/v1/transactions
  Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
  Body:
  {
    "customer": { "key": "unique_customer_id" },
    "key": "unique_transaction_id",
    "amount": 99.99,
    "action": "sale"
  }

  Important rules:
  - Send Partnero calls for ALL sign-ups and ALL purchases, not just referred
    ones. Partnero silently ignores requests with invalid keys.
  - Make Partnero API calls non-blocking. If the API is down, the sign-up or
    purchase should still succeed. Use try/catch and log errors.
  - The customer "key" must be the same value in both the sign-up and
    transaction calls — this is how Partnero links them.
  - Use the invoice/order ID as the transaction "key" so refunds can be handled
    by deleting the transaction later.

  Please find my existing sign-up and payment handlers and add the Partnero
  integration to them.
  ```
</Accordion>

### Sign-up tracking with Stripe/Paddle

Use this if your payment processor (Stripe, Paddle, Chargebee) is already connected to Partnero and handles transactions automatically. You only need to track sign-ups.

<Accordion title="Prompt: Add sign-up tracking (payment processor handles transactions)">
  ```text theme={null}
  Add Partnero affiliate sign-up tracking to my registration flow. I already
  have Stripe/Paddle connected to Partnero for transaction tracking, so I only
  need to track customer sign-ups.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  When a user signs up in my app, read the "partnero_partner" cookie from the
  HTTP request and send it to Partnero's API.

  API call:
  POST https://api.partnero.com/v1/customers
  Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
  Body:
  {
    "partner": { "key": "VALUE_FROM_PARTNERO_PARTNER_COOKIE" },
    "key": "unique_customer_id_or_email",
    "email": "user@example.com",
    "name": "First Name",
    "surname": "Last Name"
  }

  Important rules:
  - The "partnero_partner" cookie is a first-party cookie set by a frontend
    JavaScript snippet when users arrive via referral links
  - Send this for EVERY sign-up, not just referred ones. Partnero silently
    ignores requests with invalid/missing partner keys.
  - Use the user's internal ID or email as the "key" — this is what Stripe/Paddle
    uses to match transactions to customers
  - Make this call non-blocking with try/catch. If Partnero API is down, the
    sign-up should still succeed.

  The PartneroJS snippet is already installed on my frontend. Please find my
  sign-up handler and add the Partnero API call.
  ```
</Accordion>

### Transaction tracking only

<Accordion title="Prompt: Track sales for affiliate commissions">
  ```text theme={null}
  Add Partnero transaction tracking to my payment/checkout flow.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  After a successful payment, send the transaction to Partnero so the referring
  partner earns their commission.

  API call:
  POST https://api.partnero.com/v1/transactions
  Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
  Body:
  {
    "customer": { "key": "the_customer_id_used_during_signup" },
    "key": "unique_order_or_invoice_id",
    "amount": 99.99,
    "action": "sale"
  }

  Important rules:
  - customer.key must match the key used when the customer was created in Partnero
  - Use invoice/order ID as the transaction key so you can delete it for refunds
  - Send for ALL purchases — Partnero ignores transactions for non-referred customers
  - Optional fields: "product_id" and "product_type" for advanced commission rules
  - Make this non-blocking with try/catch

  For refunds, delete the transaction:
  DELETE https://api.partnero.com/v1/transactions/{transaction_key}
  Headers: Authorization: Bearer YOUR_API_KEY

  Please find my payment success handler and add the Partnero call.
  ```
</Accordion>

## Refer-a-friend program

### Full referral tracking

<Accordion title="Prompt: Add refer-a-friend tracking to my app">
  ```text theme={null}
  Integrate Partnero refer-a-friend tracking into my application.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  Context about Partnero:
  - Partnero is a referral program platform
  - API base URL: https://api.partnero.com/v1/
  - Authentication: Bearer token in Authorization header
  - API key: YOUR_API_KEY
  - Program ID: YOUR_PROGRAM_ID

  What needs to happen:

  1. FRONTEND — Add this PartneroJS snippet before </head> on all pages:
  <script>
      (function(p,t,n,e,r,o){ p['__partnerObject']=r;function f(){
      var c={ a:arguments,q:[]};var r=this.push(c);return "number"!=typeof r?r:f.bind(c.q);}
      f.q=f.q||[];p[r]=p[r]||f.bind(f.q);p[r].q=p[r].q||f.q;o=t.createElement(n);
      var _=t.getElementsByTagName(n)[0];o.async=1;o.src=e+'?v'+(~~(new Date().getTime()/1e6));
      _.parentNode.insertBefore(o,_);})(window, document, 'script', 'https://app.partnero.com/js/universal.js', 'po');
      po('settings', 'assets_host', 'https://assets.partnero.com');
      po('program', 'YOUR_PROGRAM_ID', 'load');
  </script>
  This script reads the referral key from URLs (e.g., ?ref=REFERRAL_KEY)
  and stores it in a "partnero_referral" first-party cookie.

  2. BACKEND — In my existing sign-up handler, create a customer in Partnero
  for EVERY sign-up:
  POST https://api.partnero.com/v1/customers
  Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json

  If the "partnero_referral" cookie exists (referred user):
  {
    "referring_customer": { "key": "VALUE_FROM_COOKIE" },
    "key": "unique_customer_id",
    "email": "user@example.com",
    "name": "Customer Name"
  }
  If NO cookie exists (organic sign-up, becomes a potential referrer):
  {
    "key": "unique_customer_id",
    "email": "user@example.com",
    "name": "Customer Name"
  }
  The response includes a "referral_link" field — save it for the user.

  3. BACKEND — In my payment handler, track purchases by referred customers:
  POST https://api.partnero.com/v1/transactions
  Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
  {
    "customer": { "key": "unique_customer_id" },
    "key": "unique_transaction_id",
    "amount": 99.99,
    "action": "sale"
  }

  Important rules:
  - Create ALL customers in Partnero, not just referred ones (everyone can refer)
  - Make all Partnero API calls non-blocking with try/catch
  - The customer "key" must be consistent across sign-up and transaction calls
  - Store the referral_link from the sign-up response for the user's dashboard

  Please find my sign-up and payment handlers and add the integration.
  ```
</Accordion>

### Referral dashboard

<Accordion title="Prompt: Build an in-app referral dashboard">
  ```text theme={null}
  Create a referral dashboard page where users can see their referral link,
  stats, and rewards from Partnero.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  The backend needs to call these Partnero API endpoints (all GET requests
  with header "Authorization: Bearer YOUR_API_KEY"):

  1. Customer details + referral link:
     GET https://api.partnero.com/v1/customers/{customer_id}
     Returns: referral_link, referrals_count, email, name

  2. Referral statistics:
     GET https://api.partnero.com/v1/customers/{customer_id}/stats
     Returns: click counts, referral counts, social sharing links

  3. Reward balance:
     GET https://api.partnero.com/v1/customers/{customer_id}/balance
     Returns: balance amounts by currency

  4. Referred friends:
     GET https://api.partnero.com/v1/customers/{customer_id}/referrals
     Returns: array of referred customers with name, email, status, created_at

  The dashboard UI should include:
  - The user's referral link with a "Copy link" button
  - Social share buttons (use links from the stats response)
  - Total referrals count and reward balance
  - A table of referred friends with their name and status

  Fetch all 4 endpoints in parallel from the backend. Never call the Partnero
  API from the frontend — keep the API key server-side.
  ```
</Accordion>

## Webhooks

<Accordion title="Prompt: Handle Partnero webhook events">
  ```text theme={null}
  Set up a webhook endpoint to receive real-time events from Partnero.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  Partnero sends POST requests with JSON body to your webhook URL.

  Event types:
  - partner.created, partner.updated, partner.deleted, partner.approved,
    partner.rejected, partner.archived
  - customer.created, customer.updated, customer.deleted
  - transaction.created, transaction.deleted

  Example payload:
  {
    "event": "transaction.created",
    "data": {
      "id": "txn_123",
      "amount": 99.99,
      "customer": { "key": "customer_123" }
    },
    "timestamp": "2025-05-07T10:30:00.000000Z"
  }

  Requirements:
  - Create a POST endpoint at /webhooks/partnero (or similar)
  - Parse the JSON body and route events by the "event" field
  - Return a 200 status within 5 seconds
  - Process heavy logic asynchronously (queue, background job)
  - Make the handler idempotent — Partnero retries failed webhooks, so you
    may receive the same event twice
  - Log all incoming webhook events for debugging

  Please implement this endpoint and add handlers for the event types listed.
  ```
</Accordion>

## Mobile apps

<Accordion title="Prompt: Add referral tracking to my mobile app">
  ```text theme={null}
  Integrate Partnero referral tracking into my mobile app.

  My tech stack: [DESCRIBE YOUR STACK HERE, e.g. Swift/iOS, Kotlin/Android,
  React Native, Flutter]

  Context: Partnero normally tracks referrals via browser cookies. In mobile
  apps, there are no cookies, so we extract the referral key from deep links
  and pass it to the backend.

  What needs to happen:

  1. DEEP LINK HANDLING:
     When the app opens from a URL like "yoursite.com?ref=PARTNER_KEY":
     - Extract the "ref" query parameter value
     - Store it persistently (UserDefaults on iOS, SharedPreferences on Android,
       AsyncStorage on React Native, SharedPreferences on Flutter)
     - The key should survive app restarts

  2. ON SIGN-UP:
     Include the stored referral key in the sign-up request to my backend.
     My backend then calls:
     POST https://api.partnero.com/v1/customers
     Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
     Body (for affiliate programs):
     {
       "partner": { "key": "STORED_REFERRAL_KEY" },
       "key": "unique_user_id",
       "email": "user@example.com",
       "name": "User Name"
     }
     Body (for refer-a-friend programs):
     {
       "referring_customer": { "key": "STORED_REFERRAL_KEY" },
       "key": "unique_user_id",
       "email": "user@example.com",
       "name": "User Name"
     }
     After successful creation, clear the stored referral key.

  3. ON PURCHASE:
     My backend calls:
     POST https://api.partnero.com/v1/transactions
     Headers: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json
     {
       "customer": { "key": "unique_user_id" },
       "key": "order_id",
       "amount": 49.99,
       "action": "sale"
     }

  Important: NEVER call the Partnero API from the mobile app directly.
  Always route through the backend to keep the API key secure.

  Please implement the deep link handler in the app and the API calls in
  the backend.
  ```
</Accordion>

## Refund handling

<Accordion title="Prompt: Reverse commissions on refund">
  ```text theme={null}
  When a refund happens in my app, delete the corresponding transaction in
  Partnero so the partner's commission is reversed.

  My tech stack: [DESCRIBE YOUR STACK HERE]

  API call:
  DELETE https://api.partnero.com/v1/transactions/{transaction_key}
  Headers: Authorization: Bearer YOUR_API_KEY

  The transaction_key is the unique key used when the transaction was created
  (e.g., the invoice or order ID).

  Add this to my existing refund handler. After the refund is processed with
  the payment provider, call the Partnero API to delete the transaction. Make
  it non-blocking with try/catch — the refund should succeed even if Partnero
  is unreachable.
  ```
</Accordion>