Ramp: Create a bill
Ramp bill.postBillListWithPagination: arguments, response, policy and SDK examples.
← Bill operations · Get started
Operation ramp.post_bill_list_with_pagination
Provider route: POST /developer/v1/bills. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/ramp with npm, or alter-sdk-ramp with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { RampIntegration } from "@alter-ai/ramp";
async function execute(input: Parameters<RampIntegration["bill"]["postBillListWithPagination"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new RampIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.bill.postBillListWithPagination(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_ramp import RampIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = RampIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.bill.post_bill_list_with_pagination(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | Model | Required within parent | Expand Create a bill — request body — body |
Referenced models: Create a bill — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Hold Bill — response body |
Referenced models: Hold Bill — response body
Schemas
Section titled “Schemas”23 more schemas are linked from the tables above, on the schema pages.
Create a bill — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accounting_field_selections | array | Optional | List of accounting field options selected to code the bill. |
accounting_field_selections[] | Model | Each item | Expand Create a bill — request body — body accounting field selections item |
attachment_id | JSON | Optional | |
attachment_id (anyOf 1) | string | Alternative | UUID of a previously uploaded file to attach to this bill. Default: null Format: uuid |
attachment_id (anyOf 2) | null | Alternative | |
due_at | string | Required within parent | Due date of the bill. Format: date |
enable_accounting_sync | boolean | Optional | A flag you can set to False to prevent this bill from syncing to your ERP. Note: enable_accounting_sync must be True when remote_id is provided. Default: true |
entity_id | string | Required within parent | Associated business entity. Format: uuid |
inventory_line_items | JSON | Optional | |
inventory_line_items (anyOf 1) | array | Alternative | List of inventory line items related to the bill. |
inventory_line_items (anyOf 1)[] | Model | Each item | Expand Create a bill — request body — body inventory line items List of inventory line items related to the bill item |
inventory_line_items (anyOf 2) | null | Alternative | |
invoice_currency | string | Required within parent | Currency of the invoice. One of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNH, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, EURC, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, OPEN_USD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDB, USDC, USDG, USDT, USN, UYI, UYU, UYW, UZS, VED, VES, VND, VUV, WST, XAD, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XCG, XDR, XOF, XPD, XPF, XPT, XSU, XTS, XUA, XXX, YER, ZAR, ZMW, ZWG, ZWL |
invoice_number | string | Required within parent | The invoice number on the bill. Maximum length: 84 |
issued_at | string | Required within parent | Issued date of the bill. Format: date |
line_items | JSON | Optional | |
line_items (anyOf 1) | array | Alternative | List of line items related to the bill. |
line_items (anyOf 1)[] | Model | Each item | Expand Create a bill — request body — body line items List of line items related to the bill item |
line_items (anyOf 2) | null | Alternative | |
memo | JSON | Optional | |
memo (anyOf 1) | string | Alternative | Memo of the bill. Default: null Maximum length: 1000 |
memo (anyOf 2) | null | Alternative | |
payment_date | string | Optional | For a non-card bill, the date the payment is scheduled to be initiated. If the requested date is unavailable, such as a weekend, bank holiday, past date, or same-day cutoff miss, Ramp schedules the payment for the next available initiation date. Format: date |
payment_details | JSON | Optional | |
payment_details (anyOf 1) | Model | Alternative | Expand Create a bill — request body — body payment details value Payment details for the bill. Expected schema depends on payment_method. Default: null |
payment_details (anyOf 2) | null | Alternative | |
payment_method | string | Optional | Payment method for the bill. Required unless use_default_payment_method is true. Default: UNSPECIFIED One of: ACH, CARD, CHECK, CRYPTO_WALLET_TRANSFER, DOMESTIC_WIRE, INTERNATIONAL, LOCAL_BANK_TRANSFER, ONE_TIME_CARD, ONE_TIME_CARD_DELIVERY, PAID_MANUALLY, SWIFT |
posting_date | JSON | Optional | |
posting_date (anyOf 1) | string | Alternative | The date the bill is posted to the accounting system. Default: null Format: date |
posting_date (anyOf 2) | null | Alternative | |
purchase_order_ids | array | Optional | Unique identifiers of the purchase orders to match this bill to. |
purchase_order_ids[] | string | Each item | Format: uuid |
remote_id | JSON | Optional | |
remote_id (anyOf 1) | string | Alternative | An ID that identifies the bill on the client's side. An accounting connection is required and enable_accounting_sync must be True when remote_id is provided. Omit remote_id for bills that will not be synced to an accounting provider. Default: null |
remote_id (anyOf 2) | null | Alternative | |
target_payment_arrival_date | JSON | Optional | |
target_payment_arrival_date (anyOf 1) | string | Alternative | For a bill created with use_default_payment_method=true, the target vendor arrival date. Ramp uses this date to compute the latest payment initiation date needed to target vendor arrival. If that initiation date is in the past or after today's cutoff, Ramp schedules the next valid initiation date. Default: null Format: date |
target_payment_arrival_date (anyOf 2) | null | Alternative | |
use_default_payment_method | boolean | Optional | When set to true, create the bill using the default payment method configured for the vendor. If set to true, payment_method and payment_details should not be provided. Default: false |
use_default_vendor_contact | boolean | Optional | When set to true, create the bill using the default contact configured for the vendor. If set to true, vendor_contact_id should not be provided. Default: false |
vendor_contact_id | JSON | Optional | |
vendor_contact_id (anyOf 1) | string | Alternative | Unique identifier of vendor contact, must be associated with passed vendor. Required unless use_default_vendor_contact is true. Default: null Format: uuid |
vendor_contact_id (anyOf 2) | null | Alternative | |
vendor_id | string | Required within parent | Unique identifier of bill vendor. Format: uuid |
vendor_memo | JSON | Optional | |
vendor_memo (anyOf 1) | string | Alternative | Memo to the vendor. Default: null Maximum length: 400 |
vendor_memo (anyOf 2) | null | Alternative |
Referenced models: Create a bill — request body — body accounting field selections item, Create a bill — request body — body inventory line items List of inventory line items related to the bill item, Create a bill — request body — body line items List of line items related to the bill item, Create a bill — request body — body payment details value
Create a bill — request body — body accounting field selections item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
field_external_id | string | Required within parent | Remote ID of accounting field. This is the external ID, likely from ERP system. |
field_option_external_id | JSON | Optional | |
field_option_external_id (anyOf 1) | string | Alternative | Remote ID of accounting field option. This is the external ID, likely from ERP system. Required if free_form_text is not provided. Default: null |
field_option_external_id (anyOf 2) | null | Alternative | |
free_form_text | JSON | Optional | |
free_form_text (anyOf 1) | string | Alternative | Free form text for the accounting field selection. For DATE-type fields, use ISO format (YYYY-MM-DD). Required if field_option_external_id is not provided. Default: null Minimum length: 1 |
free_form_text (anyOf 2) | null | Alternative |
Create a bill — request body — body inventory line items List of inventory line items related to the bill item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accounting_field_selections | array | Optional | |
accounting_field_selections[] | Model | Each item | Expand Create a bill — request body — body accounting field selections item |
memo | JSON | Optional | |
memo (anyOf 1) | string | Alternative | Default: null |
memo (anyOf 2) | null | Alternative | |
quantity | JSON | Required within parent | Minimum: 0 |
quantity (oneOf 1) | string | Alternative | Format: decimal |
quantity (oneOf 2) | number | Alternative | |
unit_price | JSON | Required within parent | |
unit_price (oneOf 1) | string | Alternative | Format: decimal |
unit_price (oneOf 2) | number | Alternative |
Referenced models: Create a bill — request body — body accounting field selections item
Create a bill — request body — body line items List of line items related to the bill item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accounting_field_selections | array | Optional | |
accounting_field_selections[] | Model | Each item | Expand Create a bill — request body — body accounting field selections item |
amount | JSON | Required within parent | |
amount (oneOf 1) | string | Alternative | Format: decimal |
amount (oneOf 2) | number | Alternative | |
memo | JSON | Optional | |
memo (anyOf 1) | string | Alternative | Default: null |
memo (anyOf 2) | null | Alternative |
Referenced models: Create a bill — request body — body accounting field selections item
Hold Bill — response body — bill owner
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
first_name | string | Optional | Bill owner's first name. |
id | string | Required within parent | Bill owner's ID. Format: uuid |
last_name | string | Optional | Bill owner's last name. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: ramp.post_bill_list_with_pagination. Catalog operation: post_bill_list_with_pagination. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["bills:write"]