Skip to main content

CSV exports

The CSV files the modules write: the package ledger and license register of the retention exports, the trace response zip, and, with the 3PL add-on, the owner export zip. Each file is stored with its SHA-256 and never changes afterwards. How users make and download them: Get the monthly retention export, or export on demand and Respond to a trace request.

The CSV format​

Every CSV file of the modules is the same kind of file:

  • UTF-8 text, comma-separated, quoted only where a value needs it (RFC 4180), lines ending with CRLF, one header row with the column names below;
  • an empty value means "not set"; a true flag is true (a false one is empty);
  • dates are YYYY-MM-DD, date-times YYYY-MM-DD HH:MM:SS in UTC; choice values are the stored values listed on Statuses, not the labels.

The package ledger​

package_ledger_<period>.csv, in each retention export (dscsa.retention.export, ledger_file_id; <period> is YYYY-MM for a monthly export and YYYY-MM-DD_YYYY-MM-DD for an on-demand one). One row per package per done stock move line of the period, ordered by date; the same columns form the packages.csv of a trace response.

ColumnContent
date_utcwhen the move was done
movementreceipt, shipment, customer_return, supplier_return, dropship, removal, internal, or <from usage>_to_<to usage> for another pair of location types
referencethe move's reference (the transfer number)
dscsa_documentthe DSCSA documents of the transfer, separated by ;
source_location, destination_locationthe full location names
partner, partner_glnthe trading partner (commercial entity) and its GLN
product, ndc, gtin14, serial, sgtin, lot, expiry_date, ssccthe unit
package_statethe package's current state (at the time of the export)

The list of columns and extra values per row are a documented extension point: another module can add columns after these. The 3PL add-on adds owner once the company has owner data, and names title transfers in movement (The owner column).

The license register​

license_register_<period>.csv, in the same export (license_file_id): every license of the company and every shared license, archived ones included, as of the export date.

ColumnContent
partner, partner_gln, dscsa_rolethe trading partner, its GLN and its DSCSA role
license_type, number, jurisdictionthe license; jurisdiction is the issuing state's code
issue_date, expiry_datethe license's dates
statusthe license's status on the export date
verified_on, verified_by, sourcewho verified it, when, and against which source
activetrue unless the license is archived
evidence_filesthe names of the attached evidence files, separated by ;
evidence_kept_untilfor a verified license, the date its evidence is kept until, or indefinite for a license without expiry date
companythe license's company; empty for a shared license

The trace response zip​

<request number>-response.zip (for example DSCSA-TR-2026-00001-response.zip for request DSCSA/TR/2026/00001), made by Respond on a trace request and stored on it (response_attachment_id, with its SHA-256 in response_sha256):

PathContent
request.txtthe request, its query, the results and the list of what the zip contains; times in UTC
index.csvone row per product line of each document found: document, direction, transaction_date, ship_date, partner, partner_gln, order_ref, invoice_ref, product, ndc, gtin14, lot, expiry_date, quantity, serial_count, files, sha256 (of each file, in the order of files), document_hash, and, for a supplier document whose file didn't affirm the Transaction Statement, where the statement was obtained: ts_record, ts_source, ts_obtained_on, ts_reference, ts_files, ts_sha256
packages.csvthe ledger rows of the packages found, with the package-ledger columns above; a package that never moved has one row with its state only
documents/<document number>/…each document's stored files, byte for byte; a recorded Transaction Statement and its evidence under transaction-statement/

To check a response, compare the SHA-256 of each file with index.csv, and each document's document_hash with the document (Verify Integrity checks the chain). The trace request recipe downloads a response over the external API.

The owner export zip​

With the 3PL add-on, the owner records export (dscsa.owner.export) collects one owner's records in one zip: index.csv (file, bytes, sha256 of every other file), documents.csv and the owner's documents, ledger.csv, packages.csv, stock.csv, gate_log.csv, and one CSV per kind of owner record (notices, holds, owner orders, title transfers). Every file and column is described on What the owner export zip contains, and how to verify it.