
BILL for Docusign Workflows
Get started Section 1 of 14
Quick Start
1. Prepare BILL
- A BILL administrator creates an AP & AR sync token: Settings → Sync & Integrations → Tokens → Create token, name it, click Save, and copy the value BILL shows. BILL shows it only once.
- Note your Organization ID: Settings → Sync & Integrations → Manage Developer Keys, at the bottom of the page.
- See Preparing BILL.
2. Install the App in Docusign
- Open the Docusign App Center and search for BILL.
- Open the BILL app card, click Install App, then Install and Authorize on the consent screen.
3. Connect Your BILL Organization
- On the BILL app page, click Connect Account, choose the connection visibility, name the connection, and click Log In.
- In the BILL for Docusign Workflows window, click Allow, then enter the Organization ID, the sync token's name and its value, and click Connect.
- See Connecting Your Account.
4. Create a Workflow
- In Docusign, open Workflow Manager and create a workflow.
- Choose your preferred workflow start type.
- Add a BILL step: Read, Writeback, or File Upload.
5. Available Actions
- Read from BILL: pull a Vendor, Customer, Bill or Invoice into your workflow to pre-fill an agreement.
- Writeback to BILL: create or update a vendor, customer, bill or invoice when the document is signed.
- File Upload to BILL: file the signed PDF on the record it belongs to.
6. Key Things to Know
- Search on the fields marked (Searchable), with Equal to, combined with AND. Record ID finds one record.
- The vendor of a bill and the customer of an invoice are written by Record ID: map it from an earlier Read step.
- The app reads and writes records and files. It never pays, schedules or collects money.
Reference Section 7 of 14
Supported Objects
| Step object | BILL object | Read | Search | Create | Update | File Upload |
|---|---|---|---|---|---|---|
| Vendor | Vendor (AP) | yes | yes | yes | yes | attachments |
| Customer | Customer (AR) | yes | yes | yes | yes | attachments |
| Bill | Bill (AP) | yes | yes | yes | yes | documents |
| Invoice | Invoice (AR) | yes | yes | yes | yes | attachments |
Record IDs are BILL's own ids (009… vendors, 0cu… customers, 00n… bills, 00e…
invoices). A step that receives an id of another kind fails naming the kind it expected. BILL has
no delete: records are archived in BILL, and this extension does not archive.
Fields marked (Searchable) in the field picker, and Record ID, can be used in a Read rule; every other field can be read and mapped but not used in a rule. In the object sections that follow, required means the Writeback step asks for the field on Create and on Update or Create; an Update step asks only for the fields the author adds.
Each object has its own section: Vendor, Customer, Bill, Invoice.
Reference Section 8 of 14
Vendor
A BILL vendor (payables): the company or person you pay. Record IDs start with 009. The step offers 23 fields.
| Field | Read | Search | Create | Update | Notes |
|---|---|---|---|---|---|
| Record ID | yes | Equal to | — | — | Returns the vendor even when it is archived |
| Name (Searchable) | yes | Equal to, Contains | required | yes | Up to 100 characters; BILL allows two vendors with one name |
| Account Number | yes | — | yes | yes | Up to 50 characters |
| Vendor Type (Searchable) | yes | Equal to | yes | yes | Business or Individual (BILL's vendor form); required by BILL for a vendor outside the US |
| yes | — | yes | yes | E-mail format checked by BILL; required by BILL for a vendor outside the US | |
| Phone | yes | — | yes | yes | Up to 20 characters, stored as typed |
| Address Line 1 | yes | — | required | yes | |
| Address Line 2 | yes | — | yes | yes | Up to 100 characters |
| City | yes | — | required | yes | |
| State or Province | yes | — | yes | yes | US and Canada: the two-letter code (a state or province name is converted) |
| Zip or Postal Code | yes | — | required | yes | Up to 30 characters |
| Country (Searchable) | yes | Equal to | required | yes | Two-letter ISO code (an English country name is converted) |
| Currency (Searchable) | yes | Equal to | yes | yes | Three-letter ISO code; USD when not given; required by BILL outside the US |
| Pay To Name | yes | — | yes | yes | 3–100 characters; BILL sets it to the Name at creation |
| Payment Notification Email | yes | — | yes | yes | Separate from Email |
| Tax ID | yes | — | yes | yes | Free text (BILL does not check the format) |
| Tax ID Type | yes | — | yes | yes | EIN or SSN |
| 1099 Vendor | yes | — | yes | yes | true / false (yes / no, 1 / 0); reads false when never set |
| Vendor Legal Name | yes | — | yes | yes | BILL's "Vendor legal name" under Tax information |
| Archived (Searchable) | yes | Equal to | — | — | |
| Open Balance | yes | — | — | — | BILL's amount |
| Created Time, Updated Time | yes | — | — | — | UTC instants |
Fields with a fixed set of values are listed under Picklists.
Reference Section 9 of 14
Customer
A BILL customer (receivables): the company or person you invoice. Record IDs start with 0cu. The step offers 27 fields.
| Field | Read | Search | Create | Update | Notes |
|---|---|---|---|---|---|
| Record ID | yes | Equal to | — | — | Returns the customer even when it is archived |
| Name (Searchable) | yes | Equal to | required | yes | Up to 100 characters; BILL allows namesakes |
| yes | — | required | yes | E-mail format checked by BILL | |
| Company Name | yes | — | yes | yes | Up to 250 characters |
| Contact First Name, Contact Last Name | yes | — | yes | yes | Up to 100 characters each |
| Phone | yes | — | yes | yes | Up to 20 characters, stored as typed |
| Notes About the Customer | yes | — | yes | yes | Up to 4,000 characters; line breaks kept |
| Currency (Searchable) | yes | Equal to | yes | yes | Three-letter ISO code; USD when not given |
| Customer Type (Searchable) | yes | Equal to | yes | yes | Company or Individual (BILL's customer form) |
| Account Number | yes | — | yes | yes | |
| Billing Address Line 1, Line 2, City, State or Province, Zip or Postal Code, Country | yes | — | yes | yes | On create, an address needs Line 1, City, Zip and Country together |
| Shipping Address Line 1, Line 2, City, State or Province, Zip or Postal Code, Country | yes | — | yes | yes | The same rule as the billing address |
| Archived (Searchable) | yes | Equal to | — | — | |
| Balance | yes | — | — | — | BILL's amount |
| Created Time, Updated Time | yes | — | — | — | UTC instants |
Fields with a fixed set of values are listed under Picklists.
Reference Section 10 of 14
Bill
A BILL bill (payables): a vendor's invoice to you. Record IDs start with 00n. A bill always belongs to one vendor, written by the vendor's Record ID. The step offers 19 fields.
| Field | Read | Search | Create | Update | Notes |
|---|---|---|---|---|---|
| Record ID | yes | Equal to | — | — | Returns the bill even when it is archived |
| Vendor Name (Searchable) | yes | Equal to | — | — | The bill's vendor; read-only |
| Vendor ID (Searchable) | yes | Equal to | required | yes | The vendor's Record ID; changing it moves the bill to that vendor |
| Invoice Number (Searchable) | yes | Equal to | required | yes | Up to 100 characters; BILL accepts the same number twice for one vendor |
| Invoice Date | yes | — | required | yes | A calendar day |
| Due Date (Searchable) | yes | Equal to | required | yes | A calendar day; may be before the Invoice Date |
| Bill Description | yes | — | yes | yes | Up to 4,000 characters |
| PO Number | yes | — | yes | yes | Up to 250 characters |
| Line 1 Amount | yes | — | required | yes | BILL recomputes Bill Amount and Balance Due |
| Line 1 Description | yes | — | yes | yes | |
| Line Count | yes | — | — | — | How many lines the bill holds |
| Bill Amount | yes | — | — | — | Sum of the lines |
| Paid Amount | yes | — | — | — | 0 until a payment exists |
| Balance Due | yes | — | — | — | |
| Payment Status (Searchable) | yes | Equal to | — | — | Unpaid, Partially paid, Paid, Scheduled, In process |
| Approval Status | yes | — | — | — | Unassigned, Assigned, Approving, Approved, Denied |
| Archived (Searchable) | yes | Equal to | — | — | |
| Created Time, Updated Time | yes | — | — | — | UTC instants |
Fields with a fixed set of values are listed under Picklists.
Reference Section 11 of 14
Invoice
A BILL invoice (receivables): your invoice to a customer. Record IDs start with 00e. An invoice always belongs to one customer, written by the customer's Record ID. The step offers 16 fields.
| Field | Read | Search | Create | Update | Notes |
|---|---|---|---|---|---|
| Record ID | yes | Equal to | — | — | Returns the invoice even when it is archived |
| Customer Name (Searchable) | yes | Equal to | — | — | The invoice's customer; read-only |
| Customer ID (Searchable) | yes | Equal to | required | yes | The customer's Record ID |
| Invoice Number (Searchable) | yes | Equal to | yes | yes | Up to 100 characters; unique among active invoices (any case); BILL numbers it when left blank |
| Invoice Date | yes | — | yes | yes | A calendar day; today when left blank |
| Due Date (Searchable) | yes | Equal to | yes | yes | A calendar day; today when left blank |
| Line 1 Quantity | yes | — | required | yes | |
| Line 1 Price | yes | — | yes | yes | Without a price the invoice totals 0 and BILL marks it Paid |
| Line 1 Description | yes | — | yes | yes | Up to 4,000 characters |
| Line Count | yes | — | — | — | How many lines the invoice holds |
| Invoice Amount | yes | — | — | — | Quantity × price, rounded to cents by BILL |
| Amount Due | yes | — | — | — | |
| Payment Status (Searchable) | yes | Equal to | — | — | Unpaid, Partially paid, Paid, Scheduled |
| Archived (Searchable) | yes | Equal to | — | — | |
| Created Time, Updated Time | yes | — | — | — | UTC instants |
Fields with a fixed set of values are listed under Picklists.
Reference Section 12 of 14
Picklists
Every field with a fixed set of values, with each value as you type it, as BILL stores it and as the Read step returns it. The Country and Currency lists are BILL's own (October 2026); BILL can change them.
Match rule for every list below: letter case and outer spaces are ignored ("business", " Business "); the API spelling in the "also accepted" column works too. A value outside the list stops the step with a message that names the field and the allowed values; nothing is written. Everything not listed here is free text, a number, a date or a BILL id.
Vendor Picklists
Vendor Type (Searchable) — accountType
| Type it as | Also accepted | BILL stores | The Read step returns |
|---|---|---|---|
| Business | BUSINESS, Company | BUSINESS | Business |
| Individual | PERSON | PERSON | Individual |
| None | NONE | NONE | (empty — no type set) |
BILL requires a Vendor Type for a vendor outside the US. Searching for "None" finds the vendors without a type; writing "None" clears it.
Tax ID Type — taxIdType (writable, not searchable)
| Type it as | BILL stores / returns |
|---|---|
| EIN | EIN |
| SSN | SSN |
1099 Vendor — track1099 (writable, not searchable)
| Type it as | BILL stores / returns |
|---|---|
| true, yes, 1 | true |
| false, no, 0 | false (also what a vendor reads when it was never set) |
Country (Searchable) — addressCountry
The two-letter ISO 3166-1 code, or the country's English name (converted: "United States" → US, "Canada" → CA, "United Kingdom" / "UK" → GB). The Read step returns the code. BILL accepts these 229 codes (its own list, 2026-10-16):
AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AZ BA BB BD BE BF BG BH BI BJ BM BN BO BR BS BT BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CV CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GH GI GL GM GN GP GQ GR GS GT GW GY HK HM HN HR HT HU ID IE IL IN IO IQ IS IT JM JO JP KE KG KH KI KM KN KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MG MH MK ML MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PS PT PW PY QA RE RO RS RU RW SA SB SC SE SG SH SI SJ SK SL SM SN SO SR ST SV SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VN VU WF WS YE YT ZA ZM ZW
Which countries a vendor may take depends on the organization's international payments: a new vendor outside the US also needs Email, Vendor Type and Currency, and BILL refuses moving an existing US vendor abroad where international payments are off.
Currency (Searchable) — billCurrency
The three-letter ISO 4217 code, or the currency's English name (converted: "US Dollar" → USD, "Canadian Dollar" → CAD, "Euro" → EUR). USD when not given. BILL accepts these 163 codes (its own list, 2026-10-16):
AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTN BWP BYN BZD CAD CDF CHF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP 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 MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLE SLL SOS SPL SRD STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TVD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XCD XDR XOF XPF YER ZAR ZMW ZWD
BILL checks the pair: a vendor's currency must be one BILL pays to the vendor's country.
State or Province — addressStateOrProvince (writable, not searchable)
| Country | BILL accepts | Typed names converted |
|---|---|---|
| US | the two-letter USPS code: AL AK AZ AR CA CO CT DE DC FL GA HI ID IL IN IA KS KY LA ME MD MA MI MN MS MO MT NE NV NH NJ NM NY NC ND OH OK OR PA RI SC SD TN TX UT VT VA WA WV WI WY, and PR GU VI AS MP | "Texas" → TX, "tx" → TX |
| CA | AB BC MB NB NL NS NT NU ON PE QC SK YT | "Quebec" / "Québec" → QC, "qc" → QC |
| Others | free text | — |
Archived (Searchable) — archived (read-only)
| Type it as | Means |
|---|---|
| true, yes, 1 | archived vendors |
| false, no, 0 | active vendors (also the default when the rule has no Archived condition) |
Customer Picklists
Customer Type (Searchable) — accountType
| Type it as | Also accepted | BILL stores | The Read step returns |
|---|---|---|---|
| Company | BUSINESS, Business | BUSINESS | Company |
| Individual | PERSON | PERSON | Individual |
| None | NONE | NONE | (empty — no type set) |
Currency (Searchable) — invoiceCurrency
The same codes and names as the Vendor's Currency (163 codes above); USD when not given. This organization stored USD, EUR and CAD on customers.
Billing Country, Shipping Country — billingAddressCountry, shippingAddressCountry
The same codes and names as the Vendor's Country (229 codes above). Not searchable (BILL has no country filter on customers).
Billing / Shipping State or Province
The same conversion as the Vendor's State or Province; BILL does not check a customer's state against its country.
Archived (Searchable) — archived (read-only), Customer
As for vendors.
Bill Picklists (all fixed lists are read-only)
Payment Status (Searchable) — paymentStatus
| Type it as | Also accepted | BILL stores | The Read step returns |
|---|---|---|---|
| Unpaid | UNPAID | UNPAID | Unpaid |
| Partially paid | PARTIALLY_PAID | PARTIALLY_PAID | Partially paid |
| Paid | PAID | PAID | Paid |
| Scheduled | SCHEDULED | SCHEDULED | Scheduled |
| In process | IN_PROCESS | IN_PROCESS | In process |
"Overdue" is not a status: it is BILL's badge on an unpaid bill past its due date (the step reads Unpaid).
Approval Status — approvalStatus (read-only, not searchable)
Unassigned (UNASSIGNED), Assigned (ASSIGNED), Approving (APPROVING), Approved (APPROVED), Denied (DENIED). Without an approval policy every bill is Unassigned.
Archived (Searchable) — archived (read-only), Bill
As for vendors.
Invoice Picklists (all fixed lists are read-only)
Payment Status (Searchable) — status
| Type it as | Also accepted | BILL stores | The Read step returns |
|---|---|---|---|
| Unpaid | OPEN, UNPAID | OPEN | Unpaid |
| Partially paid | PARTIAL_PAYMENT, PARTIALLY_PAID | PARTIAL_PAYMENT | Partially paid |
| Paid | PAID_IN_FULL, PAID | PAID_IN_FULL | Paid |
| Scheduled | SCHEDULED | SCHEDULED | Scheduled |
An invoice whose total is 0 or less is Paid as soon as it is created.
Archived (Searchable) — archived (read-only), Invoice
As for vendors.
Look-alike fields that are free text
| Field | Rule |
|---|---|
| Tax ID (Vendor) | Any text; BILL does not check the format |
| Phone (Vendor, Customer) | Up to 20 characters, stored as typed |
| Zip or Postal Code | Up to 30 characters, not checked against the country |
| Email, Payment Notification Email | E-mail format checked by BILL |
| Invoice Number (Bill, Invoice) | Up to 100 characters; unique among active invoices |
| Name, Pay To Name, Vendor Legal Name, Company Name, Account Number, descriptions | Free text with BILL's length limits (see Known Behaviors) |
| Vendor ID, Customer ID, Record ID | BILL ids (009…, 0cu…, 00n…, 00e…), mapped from a Read or Create step |
| Invoice Date, Due Date | A calendar day: YYYY-MM-DD (a value starting with it; the time is ignored) |
| Amounts, Line 1 Quantity, Line 1 Price | Numbers: "1500", "1,500.00", "$1,500" (not "1e3" or "77,50") |
Reference Section 13 of 14
Known Behaviors
What a workflow author meets when reading, searching, writing and uploading with BILL. The words are the ones the Docusign steps show.
Connecting
- The connection is an AP & AR sync token of ONE BILL organization: an administrator creates
it in BILL under Settings → Sync & Integrations → Tokens → Create token → Save, and enters
the Organization ID (starts with
008, shown at the bottom of Settings → Sync & Integrations → Manage Developer Keys), the token's name and its value (shown once, at creation) in the connect window. No BILL user password is ever entered or stored. - The connect window has two steps: Allow access (what the app can and cannot do in BILL), then Connect organization (the three values). If BILL rejects a value, the window stays on the second step with the Organization ID and token name kept; enter the token value again.
- Deny on the first step ends the attempt and creates no connection. Docusign then leaves an empty window open: close it.
- A connect window stays usable for 30 minutes (time to create the token in BILL). After that, or after Deny or a completed connection, the window says the request has ended: close it and select Log In again in Docusign.
- BILL checks the Organization ID and the token value; the token name is for your reference (BILL accepts the connection with any name).
- A sync-token session has no payment capability in BILL: this extension reads and writes records and files; it never pays, schedules or collects money.
Searching
- Conditions combine with AND only. A rule with OR fails with "Search filters combined with OR are not supported — combine conditions with AND, or match by Record ID". Use two Read steps when two alternatives are needed.
- Equal to is the operator on every searchable field; a Vendor's Name also takes Contains. Other operators (Not equal to, Starts with, greater / less than) fail naming the field and Equal to.
- Any field without "(Searchable)" fails naming the searchable fields of that object.
- Record ID is an anchor: a rule with Record ID returns that record and ignores the other conditions — an archived record included. A blank Record ID (the Create-or-Update pattern) returns no records, so the step creates.
- Names match exactly, ignoring letter case, extra spaces and the way an accent was typed: "acme inc" finds "Acme Inc"; "Acme" does not. A Vendor's Name with Contains finds a part of the name. A name containing a double quote is found when at least three plain characters come before the first space or quote; otherwise match it by Record ID.
- Vendor Name / Customer Name on a Bill or Invoice must match exactly ONE vendor / customer. An active one is preferred; an archived one is used only when no active one has the name. Several namesakes fail with "match by Vendor ID" (or Customer ID) — map the Record ID from an earlier Read step instead. With the Vendor ID (Customer ID) in the same rule, the name must be that vendor's (customer's) name, or no records are found.
- Invoice Number searches alone on both bills and invoices.
- Due Date matches the calendar day of the value (the time is ignored). See "Dates" below.
- Archived records are excluded unless the rule sets Archived (or uses Record ID).
- Two conditions on one field must mean the same value ("Business" and "business" do); two different values fail with "a record cannot match both".
- Several matches come back newest first (by Created Time); a Read step set to "A single record" takes the newest. Identify a record by Record ID, or a bill by Vendor ID and Invoice Number.
- A search that would have to scan more than 1,000 records fails with "narrow the filter" rather than returning a partial list.
- A new record is searchable within a few seconds of its creation.
Reading Values
- Labels and values are BILL's own words (as the BILL web app shows them): Pay To Name, Payment Notification Email, 1099 Vendor, Vendor Legal Name, Open Balance, Vendor Type (Business / Individual) on a vendor; Notes About the Customer and Customer Type (Company / Individual) on a customer; Bill Description, PO Number, Bill Amount, Balance Due on a bill; Invoice Amount, Amount Due and Payment Status on an invoice.
- "Overdue" is BILL's badge on an unpaid bill or invoice past its due date, not a Payment Status: the step reads Unpaid.
- Dates (Invoice Date, Due Date) read as the day at 00:00 UTC; Created Time and Updated Time are
instants in UTC, in the same ISO shape (
2026-10-08T16:32:23.000Z). - Country fields read the two-letter code (US), not the country's name.
- A field with no value in BILL is left out of the record (never an empty string); Paid Amount reads 0 on a bill without payments.
- Line items: Line 1 of a bill or invoice is exposed; Line Count says how many lines the record holds. Lines beyond the first are not readable or writable in this version.
Writing
- The Writeback setting decides what is asked for. Create and Update or Create ask for the fields BILL needs to create (marked required above); Update or Create adds "Overwrite if field value exists" for each mapped field. Update asks only for the fields the author adds.
- The vendor of a bill and the customer of an invoice are written by Record ID: map the Record ID from an earlier Read step (find the vendor or customer by Name there) or from the step that created it. Vendor Name and Customer Name cannot be written.
- A new customer's address is all or nothing: when any part of the Billing (Shipping) address is mapped on create, Line 1, City, Zip or Postal Code and Country of that address are needed too; the step names the missing parts before anything is written. An update writes any single part and keeps the others.
- A vendor outside the US also needs Email, Vendor Type and Currency (BILL's rule). Whether an existing US vendor can be moved abroad, or to another currency, is BILL's decision for the organization; BILL refuses it in organizations without international payments.
- Closed vocabularies are written and searched in BILL's words, any case: Vendor Type (Business, Individual), Customer Type (Company, Individual), Payment Status, Tax ID Type (EIN, SSN); the API spellings (BUSINESS, PERSON, UNPAID, OPEN, …) are accepted too, and "None" clears a Vendor / Customer Type. An unknown value fails naming the set. Booleans accept true / yes / 1 and false / no / 0.
- Country, Currency and State or Province: a country takes its two-letter code or its English name ("United States" → US), a currency its three-letter code or name ("Canadian Dollar" → CAD), a US state or Canadian province its code or name ("texas" → TX). Anything else fails naming the rule before BILL is called.
- Numbers are strict: "1,500.00", "$1,500" and "1 500" are read as 1500; "1e3" and "77,50" fail naming the field. BILL rounds amounts to cents.
- Updates are partial: only the mapped fields change; blank values are skipped, so a field cannot be cleared through the step. An update whose every mapped value is blank fails with "Nothing to write".
- Invoice Date can be changed on an existing invoice.
- Line 1 on update is addressed by the stored line; the other lines are untouched.
- A field name the app does not know (a field removed by a release, or another connector's name) stops the step with a message that names it; nothing is written. A read-only field sent beside writable ones (Archived, an amount, a status) is skipped.
- Duplicates: BILL accepts the same Invoice Number twice for one vendor's bills; invoice numbers are unique among active invoices. Use Update or Create keyed on Record ID (or Vendor ID and Invoice Number) to avoid a second bill when a workflow runs again.
- An invoice whose total is 0 or less is marked Paid by BILL at once.
- Payment set-up stays in BILL: payment terms, pay-from / pay-to accounts, card payments and classifications (account, department, location, class, item) are not exposed. BILL's own invoice email is not sent by this extension: BILL sends it only for a BILL user, and the connection is a sync token — send the invoice from BILL, or send the signed document with Docusign.
- Values BILL refuses because of the organization's settings fail with BILL's own message, in the step's field names; nothing is written.
- Writes are de-duplicated by Docusign's idempotency key: a retried step writes once and replays the first result; the same key with a different payload is refused.
Dates
- A day is stored exactly as the value states it:
2026-10-15,2026-10-15T00:00:00Zand2026-10-15T23:30:00-05:00all mean 15 October. The time and any offset are ignored, and no time zone is guessed. - A date picked from the Maestro calendar east of UTC arrives as the day before. Maestro sends
the author's local midnight converted to UTC without the offset: 15 November picked in UTC+3
arrives as
2026-11-14T21:00:00.000Z. Authors east of UTC should map the date from a field or variable written asYYYY-MM-DD, or pick the day after.
Uploading Files
- The File Upload to BILL step offers four folders — Vendors, Customers, Bills, Invoices. Pick one, then add a New Subfolder named with the record's Record ID (map it from the Read or Writeback step). Nothing else is listed under a folder.
- Vendors, customers and invoices receive the file as an attachment; a bill receives it as a document. The step waits up to about 10 seconds for BILL to process a bill document (BILL usually answers in 3 to 8 seconds): a file BILL cannot read (not a PDF or an image) stops the step naming the file — BILL still keeps it on the bill with 0 pages (remove it in BILL). When BILL takes longer than the wait, the step succeeds and BILL finishes in the background; a file it then cannot read also stays on the bill with 0 pages. BILL's virus scan takes about a minute more. Every attachment on an invoice is emailed with the invoice when BILL sends it.
- Where to find the file in BILL: a bill — open the bill (Bills → All bills → the invoice number); the signed PDF shows beside the bill details as an attached document with all its pages. An invoice — Invoices → the invoice → Edit invoice → Attachments. A vendor — Vendors → the vendor → Documents tab. A customer — Customers → the customer → its documents.
- Files up to 6 MB (6,291,456 bytes); the name keeps its extension (a nameless document is
stored as
.pdf). Leave the extension out of the name you build: Docusign adds it. - File names as BILL stores them: BILL cannot store letters outside plain English, so accents
are dropped and a few letters spelled out ("Ångström" → "Angstrom", "ß" → "ss"). Letters of
other alphabets (Cyrillic, Greek, Japanese …) have no plain spelling and become
_("Договор подписан.pdf" is stored as "_ _.pdf"): build the name in Latin letters, for example from the record's name or number.< > : " / \ | ? *become_too, and a run of_becomes one. A bill document keeps only letters, digits,.and-(spaces become_). The step's success message names the file as stored. - A workflow that runs again files another copy (BILL keeps both).
- A folder named with a Record ID BILL does not know stops the step: "No BILL Vendor has Record ID …".
What This Version Does Not Have
- No multi-value fields: every field holds one value; there is no separator rule.
- No add-only lists or history tables: an update replaces the mapped values; nothing is appended. Lines beyond Line 1 are counted (Line Count) but neither read nor written.
- No delete or archive: BILL archives instead of deleting, in BILL itself.
- No ranges or partial matches beyond a Vendor's Name Contains: no Due Date before / after, no Starts with, no Not equal to.
Messages a Step May Show
The step names a field by the label it shows in the picker. Docusign shows only the beginning of a message, so the full texts are here.
| Message (beginning) | What to do |
|---|---|
| "Search filters combined with OR are not supported" | Combine conditions with AND, or use two Read steps |
| "Vendors can't be searched by Email in this app. Searchable fields: Name, Vendor Type, Country, Currency, Archived" | Use a field marked "(Searchable)", or Record ID |
| "Vendor Type can only be searched with "Equal to" in this app" | Use Equal to |
| "Invalid value for Vendor Type: "Corporation" — expected one of Business, Individual" | Use one of the listed words (any case) |
| "Missing required fields to create a Bill: Vendor ID, …" | Map the listed fields |
| "To create a Customer with an address, BILL needs the whole address: …" | Map the missing parts, or leave the address out and add it with an update |
| "Country takes a two-letter ISO country code BILL supports (US, CA, GB …)" | Write the code or the English name |
| "Vendor ID "…" is not a BILL record in this organization" | Map the Record ID a Read or Create step returned |
| "Record ID "…" is not a BILL Vendor id (they start with 009)" | The step got another object's id or a value that is not a Record ID: map the Record ID of the right object |
| "No BILL Vendor has Record ID "…"" (update or file upload) | The record does not exist in this organization: map the Record ID a Read or Create step returned |
| "Invoice Number "…" is already used by another invoice in this organization" | Use another number, or leave it blank and BILL numbers the invoice |
| "BILL could not read "…" as a document" | Upload a PDF or an image to the bill |
| "File "…" is 6,291,457 bytes; BILL accepts files up to 6 MB (6,291,456 bytes)" | Send a smaller file: compress the PDF or split it |
| "This step reads Customer fields the BILL app no longer has: Fax (removed in v1.0.3)" | Reload Objects on the connection, re-open the step and re-map it |
| "Vendor Name matches more than one BILL vendor — match by Vendor ID instead" | Map the vendor's Record ID |
| "Nothing to write for Vendor: every mapped value is blank" | Map at least one value |
| "BILL rejected the request (400): …" | BILL's own rule, in the step's field names |
| "BILL rejected the stored sync token … reconnect the BILL connection" | The token was revoked or the organization changed: reconnect with a current token |
| "BILL could not process …" / "Failed to …" | BILL was busy or unavailable: retry |
Upgrading From a Previous Version
- v1.0.7: open App Center → Manage Apps → BILL → the connection's ⋮ menu → Reload Objects, type REFRESH to confirm, wait until the connection shows Active again (it shows Processing for a few minutes), then re-open the BILL steps. Two schema changes: the Vendor's "Account Type" is now Vendor Type and reads Business / Individual (BILL's vendor form; "Company" is still accepted when writing or searching), and an Invoice's Invoice Date can now be updated. After the reload, existing Read and Writeback steps on Vendor no longer select Vendor Type (Docusign drops a field whose label changed): open each such step → Add or Remove Fields → tick Vendor Type again, then re-map it where a later step used it. A workflow that compares a vendor's type with "Company" should compare with "Business". A step that still selects a field removed in v1.0.2 or v1.0.3 now fails naming it — re-open the step and re-map.
- v1.0.3 (labels and values in BILL's words): Reload Objects and re-open the BILL steps; only workflows that used Vendor Short Name or Customer Fax need re-mapping.
- A schema release requires Reload Objects on the BILL connection and re-opening the steps; a field whose label changed is deselected in existing steps and must be ticked again, and a renamed field must be re-mapped. Release notes say which.
Get started Section 2 of 14
Installation and Configuration
Prerequisites
- A BILL organization, and a BILL administrator who can create sync tokens.
- A Docusign account with admin rights to install and manage apps in the App Center.
Preparing BILL
The connection uses an AP & AR sync token of one BILL organization. No BILL user password is entered or stored.
-
In BILL, open Settings → Sync & Integrations → Tokens and click Create token.
-
Name the token, for example Docusign, and click Save. Copy the token value BILL shows: it is shown only once.
-
Open Settings → Sync & Integrations → Manage Developer Keys and note the Organization ID at the bottom of the page. It starts with
008.
How to Install the App
-
Open the Docusign App Center and search for BILL.
-
Click the BILL app card to open its detail page, then click Install App and Install and Authorize.
The app now appears with an Installed status.
Connecting Your Account
-
On the installed app page, click Connect Account.
-
Connection Visibility: choose how the connection is shared:
- Private: accessible only by you in Docusign.
- Shared: accessible by multiple users or the whole team.
-
Name Connection: enter a name. It appears in workflow steps, so make it easy to identify. Click Log In.
-
The BILL for Docusign Workflows window opens. Step 1, Allow access, lists what the app can and cannot do in BILL. Click Allow. Deny ends the attempt without a connection; close the window Docusign leaves open.
-
Step 2, Connect organization: enter the Organization ID, the Sync token name and the Sync token value, then click Connect.
The connection is added and ready to use in workflow steps. If BILL rejects a value, the window stays on step 2 with the Organization ID and token name kept: enter the token value again. A connect window stays usable for 30 minutes.
- One organization per connection. To work with two BILL organizations, add two connections.
- A lost token value cannot be shown again in BILL. Create a new token and reconnect.
Managing Connections
On the BILL app page, open the Manage dropdown and select Manage Connections.
Use the three-dot (⋮) menu next to a connection:
- Edit connection name: rename the connection.
- Reconnect: enter a new sync token, for example after the old one was deleted in BILL.
- Reload Objects: refresh the record types and fields. Run it after an app update that changes fields, then reopen the BILL steps (see Upgrading From a Previous Version).
- Delete Connection: remove the connection. ⚠️ This may break workflows that use it.
Adding a New Connection
Use Manage → New Connection on the app page, or + New Connection on the Connections page. Each connection appears separately in workflow steps.
Use the app Section 3 of 14
How to Use the App
Create a Workflow
-
Log in to Docusign and go to Agreements → Workflows.
-
Click Create Workflow.
-
Build your workflow using the available steps, including the BILL actions.
-
Publish the workflow when it is ready.
Available BILL Actions
Click + Add Step and search for BILL:
- Read from BILL: fetch a Vendor, Customer, Bill or Invoice and expose its fields as workflow variables. See Read from BILL.
- Writeback to BILL: create or update a vendor, customer, bill or invoice. See Writeback to BILL.
- File Upload to BILL: file a document from the workflow on a BILL record. See File Upload to BILL.
A typical vendor bill approval:
- Read from BILL: find the vendor.
- Prepare eSignature Template: pre-fill the approval with the vendor's details.
- Send Documents for Signature.
- File Upload to BILL: file the signed PDF on the vendor.
- Writeback to BILL: create the bill from the signed values, with the vendor's Record ID.
Use the app Section 4 of 14
Read from BILL
The Read from BILL step retrieves a record and exposes its fields as workflow variables.
Start the Workflow From an API Call
In this example the workflow starts From an API Call and receives the Record ID of the vendor to read.
On the workflow canvas, click Add workflow start.
-
Select a method: choose From an API Call.
-
Set up variables: add a Text variable named
vendor_id. -
Process type: choose Automated process.
Once published, the workflow has a URL your external system calls, passing vendor_id.
1. Add the Read Step
On the workflow canvas, click + Add a step below the workflow start.
Search for BILL and select Read from BILL.
2. Choose the Connection and Object
-
Connection: select the connection you created during installation.
-
BILL object: choose Vendor, Customer, Bill or Invoice. This example uses Vendor.
Click Next.
3. Select Fields to Read
Click Add or Remove Fields and tick the fields your workflow needs. The selected fields become workflow variables for later steps.
Every field of each object, and what it holds, is in Vendor, Customer, Bill and Invoice. Click Next.
4. Identify the Record to Read
Create a rule that tells the step which record to read. In this example, match the BILL Record ID to the vendor_id variable from the workflow start:
- BILL field: Record ID
- Operator: Equal to
- Workflow field:
vendor_id
Under How many records should this step return?, pick one:
- A single record: the newest record that matches.
- Multiple records: the matches, newest first.
Without a Record ID, search on the fields marked (Searchable): a vendor by Name, a bill by Vendor ID and Invoice Number, an invoice by Invoice Number. How each field matches is under Searching.
5. Preview the Step
Use preview this step to check the rule against live data, then click Apply.
Use the app Section 5 of 14
Writeback to BILL
The Writeback to BILL step creates or updates a vendor, customer, bill or invoice.
1. Add the Writeback Step
On the workflow canvas, click + Add a step where the writeback belongs, for example after the document is signed.
Search for BILL and select Writeback to BILL.
2. Choose the Object and Write Setting
-
Connection: select your BILL connection.
-
BILL object: choose Vendor, Customer, Bill or Invoice. This walkthrough creates a Bill.
-
Write settings:
- Update or Create: updates the matching record, or creates one when the rule finds nothing.
- Update: updates an existing record only.
- Create: always creates a record.
Click Next.
3. Map the Fields to Write
Click Add or Remove Fields and tick the fields you want to write. Create and Update or Create pre-select the fields BILL needs to create the record; Update asks only for the fields you add.
Each selected field then gets its own row. Map it to the workflow variable that supplies the value.
Required to create:
- Vendor: Name, Address Line 1, City, Zip or Postal Code, Country.
- Customer: Name, Email.
- Bill: Vendor ID, Invoice Number, Invoice Date, Due Date, Line 1 Amount.
- Invoice: Customer ID, Line 1 Quantity.
Vendor ID and Customer ID take a Record ID: map it from a Read from BILL step that found the vendor or customer, or from the step that created it.
⚠️ Map from the right source. The variable picker also lists the output of your Read from BILL step. Mapping a field from there writes the original value back unchanged. Map new values from the step that collected them, such as the signed document's fields.
What each field takes is in the object sections (Vendor, Customer, Bill, Invoice) and under Writing. Click Next.
4. Identify the Record to Update
For Update and Update or Create, match the record by its Record ID, for example from the Read step:
- BILL field: Record ID
- Operator: Equal to
- Workflow field: the Record ID from your Read step
A blank Record ID under Update or Create creates the record. Click Apply.
Use the app Section 6 of 14
File Upload to BILL
The File Upload to BILL step files a document produced earlier in the workflow on a vendor, customer, bill or invoice. Maximum size is 6 MB.
1. Add the File Upload Step
Add a step after signing completes, search for BILL, and select File Upload to BILL.
2. Select the File
Choose the file or envelope from an earlier step. In this example it is the Combined Envelope File from Send Documents for Signature.
3. Choose the Location
-
Select connection: your BILL connection.
-
Select drive: Vendors, Customers, Bills or Invoices, the kind of record that receives the file.
-
Click Add Folder.
4. Point the Folder at the Record
The folder holds the record's Record ID. Nothing else is listed under a drive.
-
Open the Select folder dropdown and pick New Subfolder.
-
In the New folder dialog, click Add Variable.
-
Choose the step that returns the record, select Record ID, and click Add.
-
The variable appears in the Folder name field.
-
Select folder now shows the Record ID variable. Click Next.
5. Name the File
Build the file name from Add Text and Add Variable. Leave the extension out: Docusign adds it.
BILL stores names in plain English letters: accents are dropped, and letters of other alphabets become _. A bill document keeps only letters, digits, . and -. The step's success message names the file as stored.
Click Apply.
6. Find the File in BILL
- Vendor: Vendors → the vendor → Documents tab.
- Customer: Customers → the customer → its documents.
- Invoice: Invoices → the invoice → Edit invoice → Attachments. Attachments on an invoice are emailed with it when BILL sends it.
- Bill: Bills → All bills → the bill. The PDF shows beside the bill details as an attached document with all its pages.
A workflow that runs again files another copy; BILL keeps both.
Reference Section 14 of 14
FAQ & Troubleshooting
The Read step's preview says "Unable to load data".
The rule uses a field without "(Searchable)", combines conditions with OR, or uses an operator other than Equal to. Use a field marked "(Searchable)" or Record ID, and combine conditions with AND.
"Missing required fields to create a Bill: Vendor ID".
Map the vendor's Record ID into Vendor ID, from a Read from BILL step that found the vendor or from the step that created it.
"Invalid value for Vendor Type: … expected one of Business, Individual".
Use one of the listed words, in any letter case. Every allowed value is under Picklists.
"Field "Due Date" is not a date: expected a value starting with YYYY-MM-DD".
Send dates as
2026-06-22. See Dates.
A date picked in the Maestro calendar arrives one day early.
Docusign sends the picked day as midnight in your time zone converted to UTC, so east of UTC it lands on the day before. Map the date from a field or variable written as
YYYY-MM-DD, or pick the day after.
"International payments not supported for country: CA".
BILL's own rule: an organization without international payments cannot move an existing US vendor abroad or to another currency. A new vendor outside the US also needs Email, Vendor Type and Currency.
Vendor Type is no longer selected in my step after an update.
Docusign deselects a field whose label changed when you click Reload Objects. Open the step, click Add or Remove Fields, tick Vendor Type again, and re-map it where a later step used it.
"This step reads … fields the BILL app no longer has".
The step still uses a field that a release removed. Click Reload Objects on the connection, reopen the step, and re-map it.
"BILL rejected the stored sync token … reconnect the BILL connection".
The token was deleted or the organization changed. Click Reconnect on the connection and enter a current token.
I lost the sync token value.
BILL shows it only once. Create a new token, then click Reconnect on the connection.
The file is not on the bill yet.
BILL lists a bill document within seconds and finishes its virus scan in about a minute. Refresh the bill page.
The file name in BILL differs from the one I built.
BILL stores plain English letters only, so accents are dropped and other alphabets become
_. Build the name from the record's name or number in Latin letters.
"BILL could not read … as a document".
A bill takes a PDF or an image. BILL keeps the unreadable file on the bill with 0 pages: remove it in BILL.