Partner Onboarding Flow¶

This guide describes the partner-facing onboarding flow after your OAuth2 application has been provisioned. It focuses on the order of operations and the background sync lifecycle, and links to the endpoint and concept pages that already document request details.

Before You Begin¶

Before starting this flow, make sure:

Your OAuth2 application has already been provisioned by Beyond Pricing
You have valid client credentials
You are familiar with the authentication flow and the JSON:API format

End-to-End Flow¶

Get an application-level token
Create a user
Add an account for that user
Get a user-scoped token for that user
Wait for the background sync to finish
List the user's listings and map Beyond Pricing listing IDs to your listing IDs
Enable the listing so the integration framework will begin pushing prices to the account

sequenceDiagram
    participant Partner as PartnerSystem
    participant BP as BeyondPricing

    Partner->>BP: Get app-level token
    Partner->>BP: Create user
    BP-->>Partner: Return user_id
    Partner->>BP: Add account for user
    BP-->>Partner: Queue sync
    Partner->>BP: Get user-scoped token for user
    loop Until sync completes
        Partner->>BP: List accounts for user
        BP-->>Partner: sync-status = queued/in_progress/completed
    end
    Partner->>BP: List user's listings with user-scoped token
    BP-->>Partner: listing id + channel-listings[].channel-id
    Partner->>BP: Update listing activation
    BP-->>Partner: Price syncing enabled

Step 1: Get an App-Level Token¶

Start with an application-level token so you can create the user and add the user's account. Follow the Authentication guide for token flow details and scope rules.

Note

In this onboarding flow, user and account creation use an app-level token with user:write. After the account is created, request a user-scoped token for that user so you can poll account status with user:read and retrieve listings with listings:read. See Authentication for the current scope reference.

Step 2: Create a User¶

Create the partner's user first. The user is the container for the account and for the listings that will later appear in Beyond Pricing.

Use the Create User endpoint details for the request and response schema.

Step 3: Add an Account for the User¶

After the user exists, add the partner's channel or PMS account for that user. This is the step that starts the import process for listings and reservation history.

Use the Add Account endpoint details for channel credentials, supported integrations, and response behavior.

Step 4: Get a User-Scoped Token¶

After the account exists, request a user-scoped token for that user. Use this token for user-specific reads in the remaining steps of the onboarding flow.

For collection endpoints such as List Listings, a user-scoped token automatically limits the response to the bound user, so you do not usually need to add filter[owner]={user_id}.

Step 5: Wait for the Background Sync¶

After the account is created, Beyond Pricing starts a background sync that fetches reservation history for the listings associated with that account. This can take some time, especially for accounts with many listings or a large history.

Check the account's sync-status by polling /api/v1/users/{user_id}/accounts with the List Accounts endpoint until the state reaches completed.

{
  "sync-status": {
    "state": "completed",
    "last-successful-sync-at": "2026-03-06T11:00:00+00:00"
  }
}

Warning

Do not try to map listings or enable price syncing before the account sync has finished. Until sync is complete, the listing set may still be incomplete.

Step 6: Map Beyond Pricing Listing IDs to Your Listing IDs¶

Once the sync has completed, retrieve listings with the List Listings endpoint using the user-scoped token for that user. The response is already limited to that user's listings.

The Beyond Pricing listing ID is the top-level resource id. Your listing ID from the connected channel or PMS is available in channel-listings[].channel-id.

{
  "id": "12345",
  "channel-listings": [
    {
      "channel": "hostaway",
      "channel-id": "external-listing-987"
    }
  ]
}

See the Listings endpoint reference for filtering behavior, and the JSON:API guide for collection query conventions.

Step 7: Enable a Listing¶

Listings are created disabled on the Beyond Pricing side. After you have mapped the listing IDs, enable the listing so Beyond Pricing can start pushing prices to the connected account.

Use the Listing Activation endpoint reference for the activation payload and response shape.

Note

After a listing is activated, change its nightly base price through the Base Price customization endpoint. The base price is the anchor used by Beyond Pricing's algorithm, so keeping it accurate ensures recommended prices stay aligned with the partner's expectations.

After Activation¶

After a listing has been enabled, Beyond Pricing begins the normal price-syncing lifecycle for that listing.

If you need to inspect the listing again after activation, use the Get Listing Details endpoint. For API-wide error semantics, see Error Handling.

Common Pitfalls¶

Using the wrong token type. User and account creation require an app-level token, while listing retrieval is expected to use a user-scoped token for the target user. See User-Scoped Tokens.
Starting listing mapping too early. Wait until account sync-status is completed.
Confusing Beyond Pricing listing IDs with external channel or PMS listing IDs. Use the listing resource id for Beyond Pricing and channel-listings[].channel-id for your external identifier.
Forgetting that field names are dasherized in API payloads. See JSON:API Format.