--- title: "Search billing products" method: POST path: "/api/billing-products/search" tags: ["billing_products"] --- # Search billing products `POST /api/billing-products/search` ## Request - Base URL: `https://beta.getsales.io/id/v1` - URL: `https://beta.getsales.io/id/v1/api/billing-products/search` - Auth: HTTP bearer and API key in header `Team-SID` The billing catalog: three products, data-credits (credits_pack), linkedin-sender-profiles (plan) and email-inboxes (addon), which the lines of an order hang under; nothing is priced here (quote_billing_subscription_order prices an order, the server shapes each line's price at checkout), so include prices answers no rows and limits are 0. is_active true is what is sold; the archived seats catalog stays inactive. Read-only: the catalog is authored in Paddle. page_size 0 returns the counts only. Contract: - MCP tool `search_billing_products`, registry package `mcp.id/billing_products`, mount `id.billing`. - Operation `search`, response envelope `search`. - Flags: read only. ## Request body - SearchBillingProductsRequest: Request body of `search_billing_products`. - `filter` object: Field filters, ANDed: {field: {eq | ne | in | nin | gte | lte | gt | lt | is_null}}; q inside it is free text. Omit for every row. - `q` string: Infix match over name and slug. - `sid` object: Product sid(s). - `eq` string - `in` string[] - `paddle_product_id` object: Paddle's product id. - `eq` string - `in` string[] - `is_null` boolean - `slug` object: data-credits | linkedin-sender-profiles | email-inboxes. - `eq` string - `in` string[] - `type` object: plan | addon | credits_pack. - `eq` 'plan' | 'addon' | 'credits_pack' - `ne` 'plan' | 'addon' | 'credits_pack' - `in` string[] - `nin` string[] - `is_active` object: true = the live catalog. - `eq` boolean - `created_at` object: ISO 8601 bounds. - `gte` string - `lte` string - `gt` string - `lt` string - `updated_at` object: ISO 8601 bounds. - `gte` string - `lte` string - `gt` string - `lt` string - `deleted_at` object: Default scope is { is_null: true }. - `gte` string - `lte` string - `is_null` boolean - `include` string[]: Relations to attach to every item; omit for the bare rows. - `sort` object: One column and its direction; omit for the default order. - `field` 'updated_at' | 'created_at' | 'slug', required: The column to order by. - `direction` 'asc' | 'desc': asc or desc; default desc. - `page_size` integer: 0..500, default 50; 0 = counts only, 1 = the first row. - `cursor` string, nullable: pagination.next_cursor of the previous page. ## Response `200` `search` success envelope. - SearchBillingProductsResponse - `success` true, required - `operation` 'search', required - `items` object[], required - `item` object, required - `sid` string, required: Product sid (bl_pr_...). - `paddle_product_id` string, nullable, required: Paddle's id of the product (pro_...); null on an internal sentinel. - `name` string, required: Display name. - `slug` string, required: data-credits, linkedin-sender-profiles, email-inboxes; the archived seats catalog (linkedin-seat, email-seat, credits, whitelabel) is inactive. - `type` 'plan' | 'addon' | 'credits_pack', required: plan = LinkedIn sender profiles; addon = email inbox capacity; credits_pack = data credits. - `limits` object, required: What one unit grants. - `linkedin_sender_profiles` integer: 0 on this product: the line's price carries the accounts. - `email_inboxes` integer: 0 on this product: the line's price carries the inboxes. - `credits_per_month` integer: 0 on this product: the line's price carries the credits. - `linkedin_seats` integer, required: Retired on 2026-10-25, 0. - `email_seats` integer, required: Retired on 2026-10-25, 0. - `credits_per_period` integer, required: Retired on 2026-10-25, 0. - `whitelabel` integer, required: 0: White label is part of the Business service level, not a line. - `accounts` integer: A gtm key, 0 on this product. - `cloud_browser` integer: A gtm key, 0 on this product. - `webhooks` integer: A gtm key, 0 on this product. - `is_active` boolean, required: false = no longer sold. - `visibility` 'public' | 'private', nullable, required: public = listed to buyers; private = only by a direct offer. - `created_at` string, required: ISO 8601 UTC. - `updated_at` string, required: ISO 8601 UTC. - `deleted_at` string, nullable, required: ISO 8601 UTC; null = live. - `included` object, required - `pagination` object, required - `next_cursor` string, nullable, required - `has_more` boolean, required - `total_count` integer, nullable, required - `applied_filters` object, required - `includes` string[], required - `meta` object, required - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header. - `span_id` string, required: 16 hex chars, root span of this request. - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. - `duration_ms` integer, required: Server-side wall clock. - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. - `counts` object - `total_count` number, required: Products matching the filter. - `groups` object, required: type and is_active: the count per value. ## Other responses - `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. - `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable. --- [API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)